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

FreeBSD Manual Pages

  
 
  

home | help
MOSQUITTO_CTRL(1)		   Commands		     MOSQUITTO_CTRL(1)

NAME
       mosquitto_ctrl -	a tool for initialising/configuring a Mosquitto	broker
       instance

SYNOPSIS

       mosquitto_ctrl [connection-options | -o config-file] module-name
		      module-command [command-options]

       connection-options:
			   {[-h	hostname] [--unix socket path] [-p port-number]	[-u username] [-P password]
			   | -L	URL} [-A bind-address] [-c] [-d]
			   [-i client-id] [-q message-QoS] [--quiet]
			   [-V protocol-version]
			   [[{--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]]]
			   [--proxy socks-url]

       mosquitto_ctrl [--help]

DESCRIPTION
       mosquitto_ctrl is a tool	for helping configure a	Mosquitto broker
       instance.

ENCRYPTED CONNECTIONS
       mosquitto_ctrl supports TLS encrypted connections. It is	strongly
       recommended that	you use	an encrypted connection	for all	remote use of
       mosquitto_ctrl.

       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.

MODULES
       Dynamic security
	   Authentication, and role based access control with users and
	   groups. Uses	the dynsec module name.	See: mosquitto_ctrl_dynsec(1)

       External	modules
	   mosquitto_ctrl has the ability to load external modules in the form
	   of shared libraries.	For example using the module name example will
	   try to load the external module mosquitto_ctrl_example.so or
	   mosquitto_ctrl_example.dll, depending on platform. This allows new
	   functionality to be added to	Mosquitto by combining a plugin	and
	   mosquitto_ctrl module, without having to recompile any Mosquitto
	   source code.

CONNECTION 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_ctrl or
       $HOME/.config/mosquitto_ctrl.

       The config file may be specified	manually with the -o config-file
       option.

       The config file should have 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 are	the
       message type options, of	which only one can be specified. 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.

       --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, PUBLISH, PUBREL, 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.

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

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

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

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

       -o config-file
	   Provide a path to a config file to load options from. The config
	   file	should have 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 are the message type
	   options, of which only one can be specified.	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.

       -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 to use for messages, from 0, 1 and
	   2. Defaults to 1.

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

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

       --unix
	   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_ctrl --unix /tmp/mosquitto.sock ...

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

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

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

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

          authentication-method (UTF-8	string pair)

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

          receive-maximum (16-bit unsigned integer)

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

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

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

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

          user-property (UTF-8	string pair)

   Publish
          content-type	(UTF-8 string)

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

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

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

          response-topic (UTF-8 string)

          topic-alias (16-bit unsigned	integer)

          user-property (UTF-8	string pair)

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

          user-property (UTF-8	string pair)

   Will	properties
          content-type	(UTF-8 string)

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

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

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

          response-topic (UTF-8 string)

          user-property (UTF-8	string pair)

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

EXIT STATUS
       mosquitto_sub returns zero on success, or non-zero on error. If the
       connection is refused by	the broker at the MQTT level, then the exit
       code is the CONNACK reason code.	If another error occurs, the exit code
       is a libmosquitto return	value.

       MQTT v3.1.1 CONNACK codes:

          0 Success

          1 Connection	refused: Bad protocol version

          2 Connection	refused: Identifier rejected

          3 Connection	refused: Server	unavailable

          4 Connection	refused: Bad username/password

          5 Connection	refused: Not authorized

       MQTT v5 CONNACK codes:

          0 Success

          128 Unspecified error

          129 Malformed packet

          130 Protocol	error

          131 Implementation specific error

          132 Unsupported protocol version

          133 Client ID not valid

          134 Bad username or password

          135 Not authorized

          136 Server unavailable

          137 Server busy

          138 Banned

          139 Server shutting down

          140 Bad authentication method

          141 Keep alive timeout

          142 Session taken over

          143 Topic filter invalid

          144 Topic name invalid

          147 Receive maximum exceeded

          148 Topic alias invalid

          149 Packet too large

          148 Message rate too	high

          151 Quota exceeded

          152 Administrative action

          153 Payload format invalid

          154 Retain not supported

          155 QoS not supported

          156 Use another server

          157 Server moved

          158 Shared subscriptions not	supported

          159 Connection rate exceeded

          160 Maximum connect time

          161 Subscription IDs	not supported

          162 Wildcard	subscriptions not supported

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

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

AUTHOR
       Roger Light <roger@atchoo.org>

Mosquitto Project		  04/12/2025		     MOSQUITTO_CTRL(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mosquitto_ctrl&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help