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>