mosquitto_ctrl_shell man page

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.

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

Author

Roger Light <roger@atchoo.org>