The Mosquitto_ctrl tool was introduced with mosquitto v2 and is used for dynamically making user and ACL changes on a mosquitto broker.

To use it the target broker needs to have the dynamic security plugin enabled.

The tool is effectively a modified mosquitto publish client and if you subscribe to the $CONTROL topic you can see the messages that it publishes (example shown below).

Command Summary Table

The table below gives a summary of commands and a brief description. You should note that.

1. Commands use camel case notation e.g getClient and not getclient
2. There are commands to list all clients, all groups, all roles
3. There are commands to list client details, group details, role details
4. There a commands to create and remove clients, groups and roles

Example Usage

Client Examples

C:\m21>mosquitto_ctrl -h 192.168.1.91 -u steve -P password dynsec createClient john
Enter new password for john. Press return for no password (user will be unable to login).
New password for john:
Reenter password for john:
Warning: You are running mosquitto_ctrl without encryption.
This means all of the configuration changes you are making are visible on the network, including passwords.

C:\m21>mosquitto_ctrl -h 192.168.1.91 -u steve -P password dynsec getClient john
Warning: You are running mosquitto_ctrl without encryption.
This means all of the configuration changes you are making are visible on the network, including passwords.

Username: john
Clientid:

Group Examples

C:\1>mosquitto_ctrl -h 192.168.1.91 -u steve -P password dynsec createGroup test
Warning: You are running mosquitto_ctrl without encryption.
This means all of the configuration changes you are making are visible on the network, including passwords.

createGroup: Error: Group already exists

C:\1>mosquitto_ctrl -h 192.168.1.91 -u steve -P password dynsec listGroups
Warning: You are running mosquitto_ctrl without encryption.
This means all of the configuration changes you are making are visible on the network, including passwords.

anonymous
test
C:\1>mosquitto_ctrl -h 192.168.1.91 -u steve -P password dynsec getClient john
Warning: You are running mosquitto_ctrl without encryption.
This means all of the configuration changes you are making are visible on the network, including passwords.

Username: john
Clientid:
Roles:    role2 (priority: -1)
Groups:   test (priority: -1)

Role Examples

C:\m21>mosquitto_ctrl -h 192.168.1.91 -u steve -P password dynsec createRole role1
Warning: You are running mosquitto_ctrl without encryption.
This means all of the configuration changes you are making are visible on the network, including passwords.


C:\m21>mosquitto_ctrl -h 192.168.1.91 -u steve -P password dynsec listRoles
Warning: You are running mosquitto_ctrl without encryption.
This means all of the configuration changes you are making are visible on the network, including passwords.

admin
role1

ACL examples

C:\m21>mosquitto_ctrl -h 192.168.1.91 -u steve -P password dynsec addRoleACL role1 subscribePattern testtopic allow

Warning: You are running mosquitto_ctrl without encryption.
This means all of the configuration changes you are making are visible on the network, including passwords.
C:\m21>mosquitto_ctrl -h 192.168.1.91 -u steve -P password dynsec addRoleACL role1 subscribePattern testtopic2 allow 5
Create client(user)

C:\m21>mosquitto_ctrl -h 192.168.1.91 -u steve -P password dynsec getDefaultACLAccess
Warning: You are running mosquitto_ctrl without encryption.
This means all of the configuration changes you are making are visible on the network, including passwords.

publishClientSend    : deny
publishClientReceive : allow
subscribe            : deny
unsubscribe          : allow

Testing Notes:

Because the server doesn’t always send a reason code back to the client if it is denied then you will need to have another client connected that has complete access to check that publish and subscribe work.

For example you may be subscribed to a topic and the reason you don’t see messages is because the publishing client is denied or that you are denied subscribe.

Useful Tools

Bash script tool for managing security using mosquitto_ctrl – I haven’t tried it yet but if you try it you may want to let me know how it was.

I also have a node-red tool that allows you to manage security using mosquitto_ctrl. A screen shot is below:

Importunately I got side tracked and never finished testing it and so I didn’t make it available.
Let me know if you would be interested in the tool.

 Loading ...

Related Tutorials and Resources

• Understanding and Using the Mosquitto Dynamic Security Plugin
• Using The Mosquitto_pub and Mosquitto_sub MQTT Client Tools- Examples
• Dynsec manual