mosquitto_ctrl 1 Mosquitto Project Commands mosquitto_ctrl_shell a interactive shell for configuring a Mosquitto broker instance mosquitto_ctrl -h hostname -p port-number -u username -P password -i client-id --cafile file --capath dir --cert file --key file 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. 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. 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 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. 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. 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. 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. 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. The options below may be given on the command line mosquitto_ctrl returns zero on success, or non-zero on error. mosquitto 7 mqtt 7 mosquitto_ctrl 1 mosquitto_rr 1 mosquitto_pub 1 mosquitto_sub 1 mosquitto 8 libmosquitto 3 mosquitto-tls 7 Roger Light roger@atchoo.org