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
getRole 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 acltype 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.

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:

mos-ctrl-node-red
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.

Would you be Interested in the Node-red tool to manage ACls using mosquitto_ctrl

View Results

Loading ... Loading ...

 

Related Tutorials and Resources

Please rate? And use Comments to let me know more

18 comments

  1. Hey,
    good information. After having a lot of hassle back and forth with all the mosquitto_ctrl commands, I’ve put a bash script together, based on the input of this article.
    It’s on github, in case it is useful for someone else as well. (as I’ve searched a lot for any tools making life easier, but there was nothing availabile)
    https://github.com/tjareson/easymq

    1. Tks for the link I will check it out. I did a similar thing but using node-red but A bash script is more universal.
      Rgds
      Steve

  2. Hi steve
    I’m using paho library in python to manage my mqtt server. I set specific username & password and specific topic for every client, for this, I create a new role with two ACLs (for publish a topic and subscribe a topic for this client) and then i create a new client and assign this created role. i do these works with 4 commands
    but mosquitto has bad delay for running multiple commands. and I can’t run many commands with together.
    mosquitto runs a package of commands correctly and it has no problem but it can’t run packages one after other. i think that it needs a queue structure. what’s your idea Steve?
    I may want to run commands in different places of my application, and I don’t know mosquitto executed the previous command or not.
    help me please, thanks

  3. Hi Steve, I was able to get the example in your guide working. But the moment I do a `systemctl restart mosquitto.service`, all my users and roles are “erased” from run time. And I need to repeat all the `mosquitto_ctrl` commands again. Is there a way to tell `mosquitto_ctrl` to “remember” all the users and roles I created even after a system reboot? I’ve also asked this question on stack overflow here, so hopefully someone gives me an answer:

    https://stackoverflow.com/questions/71197601/prevent-systemctl-restart-mosquitto-service-from-resetting-dynamic-security

    Also, every time I manually add users and roles to the `dynamic-security.json` file, the changes only take effect after I `systemctl restart mosquitto.service`. Is that to be expected?

    1. John
      The settings should be stored in the json file and hence take affect after restart. Manually adding to the file you would expect that you needed a restart and is what I observed. I will check your first point as I haven’t used the tool for a while. What version of mosquitto are you on?
      rgds
      steve

  4. Hi Steve ,
    I was wondering if mosquitto_ctrl commands can be used in codes?
    Have you tried this before.?
    It would be much better if we can build an application that makes your life easier managing clients ,groups and roles , topic access ….etc.

        1. You can quite easily do this in any language that can send MQTT messages.

          You just need to send a JSON string to $CONTROL/dynamic-security/v1

          For example to add a user the JSON is

          { “command”: “createClient”, “username”:”xxx”,”password”:”yyy”,”clientid”:”ccc”
          }
          The command matches the various commands used in mosquitto_ctrl.
          You can also string multiple commands and send them in one message, so you can create a user and set roles in 1 message.

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

  6. 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 to steve Cancel reply

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