mosquitto_ctrl_shell - Man Page

a interactive shell for configuring a Mosquitto broker instance

Synopsis

mosquitto_ctrl [-h hostname] [-p port-number] [-u username] [-P password] [-i client-id] [--cafile file] [--capath dir] [--cert file --key file]

Description

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

This man page describes how to use the interactive shell​. For information on the pure command line mode, see mosquitto_ctrl(1)​. The interactive shell makes most operations very straightforward and is recommended for ease of use​.

To run in interactive mode, run mosquitto_ctrl with no module or command, i​.e​. with at most the set of options described in the synopsis above​. The shell will start and you will be presented with a prompt​.

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, connect using the mqtts:// or wss:// scheme inside the shell, or use either --cafile or --capath when starting mosquitto_ctrl on the command line - this also allows custom CA certificates to be used​.

Client certificates may be used for additional security​. To enable this, use the --cert and --key options​.

Example Shell Workflow

Example ​1. ​

The typical workflow for using the interactive shell is to configure authentication and connect to a broker, then switch to the mode you are interested in and run its commands​. For example, to create a new group in the dynamic-security plugin:

$ mosquitto_ctrl
mosquitto_ctrl shell v2​.1​.0
> auth
username: admin
password:
> connect mqtt://localhost
mqtt://localhost:1883> dynsec
mqtt://localhost:1883|dynsec> createGroup newgroup
OK

Shell Behaviour

The interactive shell operates in a set of different modes which have different commands available​. The shell has tab completion for the commands and their arguments, where possible​. It should usually be possible to press the tab key twice to be able to be shown a list of the currently available commmands or arguments​.

The shell has a history of commands that can be accessed by pressing the up and down arrow keys​. The history is not saved to disk​.

Help can be obtained for any command by typing help followed by the command name​. For example: help createGroup​.

The different modes are:

Pre-connection

In this mode it is possible to set the authentication details, connect to a broker, read help and exit​.

Post-connection

In this mode, mosquitto_ctrl is connected to a broker and you can switch between different control modules, view help or exit​.

dynsec

Allows you to create, delete, and modify users, groups, roles, and ACLs​.

broker

Allows you to view listener and plugin information​.

Authentication

mosquitto_ctrl supports authentication via username and password, or via x509 client certificates​. If you are using username and password authentication, then you must set the username and password before connecting​. This can be done in one of two ways​. The first is by using the -u and -P options on the command line​. The second is by using the auth command in the shell​.

Authentication in the shell can done in one of two ways​. The first is by using the auth command, which will then prompt for a username and password​. The second is by using the auth username command, which will then prompt for a password​.

Connection

To connect to a broker, use the connect command​.

If the -h option is used on the command line, the shell will immediately attempt to connect to the host specified​.

Dynamic-Security Mode

Once connected, you can use the command dynsec to switch to the dynamic-security mode​. This will only work if the broker has the dynamic-security plugin loaded, and you have permission to use it​.

The dynamic-security mode has commands to create, delete, and modify users, groups, roles, and ACLs​. The commands can be discovered by pressing the tab key twice​. Usernames, group names, and role names can be auto-completed for the appropriate commands by pressing the tab key​. Help is available for each command by using help followed by the command name​.

To leave the dynamic-security mode, use the return command, or use the exit command to exit the shell​.

Broker Mode

Use the command broker to switch to the broker mode​. This will only work if the broker has the enable_control_api option set to true​.

The broker mode has the commands listListeners, to show currently configured listener configuration, and listPlugins, to show currently loaded plugins​.

To leave the broker mode, use the return command, or use the exit command to exit the shell​.

Connection Options

The options below may be given on the command line

--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 and the Encrypted Connections section​.

--ciphers

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

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

--key

Define the path to a file containing a PEM encoded private key for this client, carrying out mutual TLS with the server​.

See also --cert and the Encrypted Connections section​.

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

-u,  --username

Provide a username to be used for authenticating with the broker​.

See also the --pw argument​.

Exit Status

mosquitto_ctrl returns zero on success, or non-zero on error​.

Bugs

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

See Also

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

Author

Roger Light <roger@atchoo​.org>

Info

11/18/2026 Mosquitto Project Commands