MOSQUITTO_CTRL(1)

📦
version 2.1.2 · 5 versions
, in alpine 3.24, fedora 44

💅 MOSQUITTO_CTRL(1) — the interactive shell era

okay so real talk, bestie, this is the manual page for mosquitto_ctrl, manual section 1, and it's literally the glow-up guide for the interactive shell. if you've been out here typing full commands like it's 2015, this page is your sign to switch to shell mode. it's giving convenience, it's giving tab-completion, it's giving main character energy 🎀

✨ NAME ✨

mosquitto_ctrl_shell — an interactive shell for configuring a Mosquitto broker instance. yes, "a interactive" is how the original says it, we don't fix what's iconic 💅

🌸 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 the tool that helps you configure a Mosquitto broker instance, and honestly it ate.

This man page is specifically about the interactive shell life. For the pure command line mode, go read mosquitto_ctrl(1) — different vibe, different page. The interactive shell makes most operations super straightforward and it's lowkey the recommended way to do things because ease of use is the whole point 🫶

To run in interactive mode, run mosquitto_ctrl with no module or command — like, at most just the set of options described in the synopsis above. The shell will start and you'll be presented with a prompt. that's it. that's the whole ritual ✨

🔒 ENCRYPTED CONNECTIONS 🔒

mosquitto_ctrl supports TLS encrypted connections, and it is strongly recommended that you use an encrypted connection for all remote use of mosquitto_ctrl. no cap, protect yourself 💖

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 — that also lets you use custom CA certificates, which is a slay.

Client certificates may be used for additional security. To enable this, use the --cert and --key options. mutual TLS said "let me introduce myself" 😭

🎀 EXAMPLE SHELL WORKFLOW 🎀

Example 1.

The typical workflow for using the interactive shell is: configure authentication and connect to a broker, then switch to the mode you're interested in and run its commands. like, get dressed then go out. 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

see how the prompt evolves? that's character development 🦋

⭐ SHELL BEHAVIOUR ⭐

The interactive shell operates in a set of different modes, and each mode has 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 shown a list of the currently available commmands or arguments. (yes, "commmands" — three m's, we're keeping it, it's part of the lore 💀)

The shell has a history of commands that you can access by pressing the up and down arrow keys. The history is not saved to disk — it lives in the moment, like all of us 🦋

Help can be obtained for any command by typing help followed by the command name. For example: help createGroup. it's literally that easy.

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're using username and password authentication, then you must set the username and password before connecting. There are two ways to do this, bestie:

  1. Use the -u and -P options on the command line.
  2. Use the auth command in the shell.

Authentication in the shell can be done in one of two ways (yes, the original says this twice, and honestly? same energy):

  1. Use the auth command, which will then prompt for a username and password.
  2. Use the auth username command, which will then prompt for a password.

🧚 CONNECTION 🧚

To connect to a broker, use the connect command. here's the whole menu, pick your fighter:

  • 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. no small talk, straight to business 🔥

👑 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. vibe check first, always 🙈

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 — which is honestly so satisfying. 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. read the room, check the config 💅

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. every single one, no skips, we're thorough here:

  • --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. no, you can't skip it, yes, it's annoying 😭

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. binary queen, no in-between 💅

💀 BUGS 💀

mosquitto bug information can be found at https://github.com/eclipse-mosquitto/mosquitto/issues. report it, don't suffer in silence bestie 🍓

🌸 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> — icon, legend, the moment 👑

and that's the page, bestie. go forth, tab-complete, and use TLS. 💖

this masterpiece brought to you by the Mosquitto Project, dated 02/09/2026, page MOSQUITTO_CTRL(1) — see you in the group chat 🎀✨

📦 where this page comes from