Using the Mosquitto_ctrl Tool

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).



mosquitto-control-topic

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

Mosquitto_ctrl Command Summary

command

parameters

Description

Notes

Client Commands

listClients none Lists all clients
getClient Client name Displays information on client
Createclient Client name and optional client_id Creates a new client (user)
deleteClient Client name Deletes a client (user)
disableClient Client name Disables client
enableClient Client name Enables client
setClientPassword Client name and password Sets password for client (user)
addClientRole Client name and Role Adds a role to a client The Role  must already exist
removeClientRole Client name and Role Removes  role from  a client

Groups

listGroups Lists all groups
getGroup Group name Displays information on group
createGroup Group name Creates a new group
deleteGroup Group name Deletes a group
addGroupClient Group name client name priority(optional) Adds a group to a client
removeGroupClient Group name client name remove a group from a client
addGroupRole Group name Role name priority(optional) Adds a group to a role
removeGroupRole Group name Role name remove a group from a role

Roles

listRoles Lists all roles
getRoles Role name Displays information on a role
createRole Role name Creates a new role
deleteRole Role name Deletes a role
addRoleACL Role name  acltype Topic allow/deny priority(optional) Adds an ACL to a role Where acltype is one of publishClientSend, publishClientReceive, subscribeLiteral, subscribePattern, unsubscribeLiteral, and unsubscribePattern.
removeRoleACL Role name  Topic Removes an ACL from a role

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.

Related Tutorials and Resources

Please rate? And use Comments to let me know more

6 comments

  1. Hi Steve,

    After submitting my previous comment, I read it again and found my previous reply’s content is changed by the website system. I am submitting another comment here to correct the command changed by system. it is as the following

    mosquitto_ctrl -u admin-user -h localhost dynsec createClient clientName -c clientId

  2. Hi Thanks for the greate article. I got a question for creating client with clientid using mosquitto_ctrl tool.

    I have setup the Dynamic Security Plugin and I am able to use the mosquitto_ctrl tool to create client wihtout any id.

    However, when I try to create client with ID using the following command.

    [code]mosquitto_ctrl -u cyno -h localhost dynsec createClient myClient1 -i clientid111[/code]

    The client is created but no clientid is associated with the client. I don’t know what mistake I am making here and anyone please help? Thanks a lot!!!

    1. Hi
      I tried and got the same result I will see if I can find an answer. If you discover anything let me know
      rgds
      steve

      1. Hi Steve,

        I got the solution from one of the mosquitto project contributors. Here is how.

        Instead of using -i, we should use -c to create client with client id associated to it. The following is the complete command for creating client with client id associated to it.

        mosquitto_ctrl -u admin-user -h dynsec createClient -c

        The following link is from Mosquitto Github’s issue page. I opened an issue there asking for help and got the above solution. For more details please refer to the following link

        https://github.com/eclipse/mosquitto/issues/2273

Leave a Reply

Your email address will not be published. Required fields are marked *