FreeBSD Manual Pages
MOSQUITTO_CTRL(1) Commands MOSQUITTO_CTRL(1) NAME mosquitto_ctrl_shell - 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. • Connect to the broker at localhost on port 1883. > connect • Connect to a specific broker using the default port 1883. > connect mqtt://test.mosquitto.org • Connect to a specific broker using the specific port 1884. > connect mqtt://test.mosquitto.org:1884 • Connect to a specific broker using TLS. > connect mqtts://test.mosquitto.org • Connect to a specific broker using websockets. > connect ws://test.mosquitto.org • Connect to a specific broker using websockets over TLS. > connect wss://test.mosquitto.org 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> Mosquitto Project 06/11/2026 MOSQUITTO_CTRL(1)
NAME | SYNOPSIS | DESCRIPTION | ENCRYPTED CONNECTIONS | EXAMPLE SHELL WORKFLOW | SHELL BEHAVIOUR | AUTHENTICATION | CONNECTION | DYNAMIC-SECURITY MODE | BROKER MODE | CONNECTION OPTIONS | EXIT STATUS | BUGS | SEE ALSO | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mosquitto_ctrl_shell&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>