'\" t
.\"     Title: mosquitto_ctrl
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/26/2026
.\"    Manual: Commands
.\"    Source: Mosquitto Project
.\"  Language: English
.\"
.TH "MOSQUITTO_CTRL" "1" "03/26/2026" "Mosquitto Project" "Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mosquitto_ctrl_shell \- a interactive shell for configuring a Mosquitto broker instance
.SH "SYNOPSIS"
.HP \w'\fBmosquitto_ctrl\fR\ 'u
\fBmosquitto_ctrl\fR [\fB\-h\fR\ \fIhostname\fR] [\fB\-p\fR\ \fIport\-number\fR] [\fB\-u\fR\ \fIusername\fR] [\fB\-P\fR\ \fIpassword\fR] [\fB\-i\fR\ \fIclient\-id\fR] [\fB\-\-cafile\fR\ \fIfile\fR] [\fB\-\-capath\fR\ \fIdir\fR] [\fB\-\-cert\fR\ \fIfile\fR\ \fB\-\-key\fR\ \fIfile\fR]
.SH "DESCRIPTION"
.PP
\fBmosquitto_ctrl\fR
is a tool for helping configure a Mosquitto broker instance\&.
.PP
This man page describes how to use the interactive shell\&. For information on the pure command line mode, see
\fBmosquitto_ctrl\fR(1)\&. The interactive shell makes most operations very straightforward and is recommended for ease of use\&.
.PP
To run in interactive mode, run
\fBmosquitto_ctrl\fR
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\&.
.SH "ENCRYPTED CONNECTIONS"
.PP
\fBmosquitto_ctrl\fR
supports TLS encrypted connections\&. It is strongly recommended that you use an encrypted connection for all remote use of mosquitto_ctrl\&.
.PP
To enable TLS connections, connect using the
\fBmqtts://\fR
or
\fBwss://\fR
scheme inside the shell, or use either
\fB\-\-cafile\fR
or
\fB\-\-capath\fR
when starting mosquitto_ctrl on the command line \- this also allows custom CA certificates to be used\&.
.PP
Client certificates may be used for additional security\&. To enable this, use the
\fB\-\-cert\fR
and
\fB\-\-key\fR
options\&.
.SH "EXAMPLE SHELL WORKFLOW"
.PP
\fBExample\ \&1.\ \&\fR
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
$ 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
.fi
.if n \{\
.RE
.\}
.SH "SHELL BEHAVIOUR"
.PP
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\&.
.PP
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\&.
.PP
Help can be obtained for any command by typing
\fBhelp\fR
followed by the command name\&. For example:
\fBhelp createGroup\fR\&.
.PP
The different modes are:
.PP
\fBPre\-connection\fR
.RS 4
In this mode it is possible to set the authentication details, connect to a broker, read help and exit\&.
.RE
.PP
\fBPost\-connection\fR
.RS 4
In this mode, mosquitto_ctrl is connected to a broker and you can switch between different control modules, view help or exit\&.
.RE
.PP
\fBdynsec\fR
.RS 4
Allows you to create, delete, and modify users, groups, roles, and ACLs\&.
.RE
.PP
\fBbroker\fR
.RS 4
Allows you to view listener and plugin information\&.
.RE
.SH "AUTHENTICATION"
.PP
\fBmosquitto_ctrl\fR
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
\fB\-u\fR
and
\fB\-P\fR
options on the command line\&. The second is by using the
\fBauth\fR
command in the shell\&.
.PP
Authentication in the shell can done in one of two ways\&. The first is by using the
\fBauth\fR
command, which will then prompt for a username and password\&. The second is by using the
\fBauth\fR
\fIusername\fR
command, which will then prompt for a password\&.
.SH "CONNECTION"
.PP
To connect to a broker, use the
\fBconnect\fR
command\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Connect to the broker at localhost on port 1883\&.
.sp
.if n \{\
.RS 4
.\}
.nf
> connect
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Connect to a specific broker using the default port 1883\&.
.sp
.if n \{\
.RS 4
.\}
.nf
> connect mqtt://test\&.mosquitto\&.org
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Connect to a specific broker using the specific port 1884\&.
.sp
.if n \{\
.RS 4
.\}
.nf
> connect mqtt://test\&.mosquitto\&.org:1884
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Connect to a specific broker using TLS\&.
.sp
.if n \{\
.RS 4
.\}
.nf
> connect mqtts://test\&.mosquitto\&.org
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Connect to a specific broker using websockets\&.
.sp
.if n \{\
.RS 4
.\}
.nf
> connect ws://test\&.mosquitto\&.org
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Connect to a specific broker using websockets over TLS\&.
.sp
.if n \{\
.RS 4
.\}
.nf
> connect wss://test\&.mosquitto\&.org
.fi
.if n \{\
.RE
.\}
.RE
.PP
If the
\fB\-h\fR
option is used on the command line, the shell will immediately attempt to connect to the host specified\&.
.SH "DYNAMIC\-SECURITY MODE"
.PP
Once connected, you can use the command
\fBdynsec\fR
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\&.
.PP
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
\fBhelp\fR
followed by the command name\&.
.PP
To leave the dynamic\-security mode, use the
\fBreturn\fR
command, or use the
\fBexit\fR
command to exit the shell\&.
.SH "BROKER MODE"
.PP
Use the command
\fBbroker\fR
to switch to the broker mode\&. This will only work if the broker has the
\fBenable_control_api\fR
option set to true\&.
.PP
The broker mode has the commands
\fBlistListeners\fR, to show currently configured listener configuration, and
\fBlistPlugins\fR, to show currently loaded plugins\&.
.PP
To leave the broker mode, use the
\fBreturn\fR
command, or use the
\fBexit\fR
command to exit the shell\&.
.SH "CONNECTION OPTIONS"
.PP
The options below may be given on the command line
.PP
\fB\-\-cafile\fR
.RS 4
Define the path to a file containing PEM encoded CA certificates that are trusted\&. Used to enable SSL communication\&.
.sp
See also
\fB\-\-capath\fR
.RE
.PP
\fB\-\-capath\fR
.RS 4
Define the path to a directory containing PEM encoded CA certificates that are trusted\&. Used to enable SSL communication\&.
.sp
For
\fB\-\-capath\fR
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\&.
.sp
See also
\fB\-\-cafile\fR
.RE
.PP
\fB\-\-cert\fR
.RS 4
Define the path to a file containing a PEM encoded certificate for this client, if required by the server\&.
.sp
See also
\fB\-\-key\fR
and the Encrypted Connections section\&.
.RE
.PP
\fB\-\-ciphers\fR
.RS 4
An openssl compatible list of TLS ciphers to support in the client\&. See
\fBciphers\fR(1)
for more information\&.
.RE
.PP
\fB\-\-help\fR
.RS 4
Display usage information\&.
.RE
.PP
\fB\-h\fR, \fB\-\-host\fR
.RS 4
Specify the host to connect to\&. Defaults to localhost\&.
.RE
.PP
\fB\-i\fR, \fB\-\-id\fR
.RS 4
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
\fBmosq\-XXXXXXXXXXXXXXXXXX\fR, where the
\fBX\fR
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\&.
.RE
.PP
\fB\-\-key\fR
.RS 4
Define the path to a file containing a PEM encoded private key for this client, carrying out mutual TLS with the server\&.
.sp
See also
\fB\-\-cert\fR
and the Encrypted Connections section\&.
.RE
.PP
\fB\-p\fR, \fB\-\-port\fR
.RS 4
Connect to the port specified\&. If not given, the default of 1883 for plain MQTT or 8883 for MQTT over TLS will be used\&.
.RE
.PP
\fB\-u\fR, \fB\-\-username\fR
.RS 4
Provide a username to be used for authenticating with the broker\&.
.sp
See also the
\fB\-\-pw\fR
argument\&.
.RE
.SH "EXIT STATUS"
.PP
mosquitto_ctrl returns zero on success, or non\-zero on error\&.
.SH "BUGS"
.PP
\fBmosquitto\fR
bug information can be found at
\m[blue]\fB\%https://github.com/eclipse-mosquitto/mosquitto/issues\fR\m[]
.SH "SEE ALSO"
\fBmosquitto\fR(7), \fBmqtt\fR(7), \fBmosquitto_ctrl\fR(1), \fBmosquitto_rr\fR(1), \fBmosquitto_pub\fR(1), \fBmosquitto_sub\fR(1), \fBmosquitto\fR(8), \fBlibmosquitto\fR(3), \fBmosquitto-tls\fR(7)
.SH "AUTHOR"
.PP
Roger Light
<roger@atchoo\&.org>