660 lines
9.3 KiB
Markdown
660 lines
9.3 KiB
Markdown
# Mosquitto Dynamic Security
|
|
|
|
This document describes a topic based mechanism for controlling security in
|
|
Mosquitto. JSON commands are published to topics like `$CONTROL/<feature>/v1`
|
|
|
|
## Clients
|
|
|
|
When a client connects to Mosquitto, it can optionally provide a username. The
|
|
username maps the client instance to a client on the broker, if it exists.
|
|
Multiple clients can make use of the same username, and hence the same broker
|
|
client.
|
|
|
|
## Groups
|
|
|
|
Broker clients can be defined as belonging to zero or more broker groups.
|
|
|
|
## Roles
|
|
|
|
Roles can be applied to a client or a group, and define what that client/group
|
|
is allowed to do, for example what topics it may or may not publish or
|
|
subscribe to.
|
|
|
|
## Commands
|
|
|
|
### Set default ACL access
|
|
|
|
Sets the default access behaviour for the different ACL types, assuming there
|
|
are no matching ACLs for a topic.
|
|
|
|
By default, publishClientSend and subscribe default to deny, and
|
|
publishClientReceive and unsubscribe default to allow.
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "setDefaultACLAccess",
|
|
"acls":[
|
|
{ "acltype": "publishClientSend", "allow": false },
|
|
{ "acltype": "publishClientReceive", "allow": true },
|
|
{ "acltype": "subscribe", "allow": false },
|
|
{ "acltype": "unsubscribe", "allow": true }
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec setDefaultACLAccess subscribe deny
|
|
```
|
|
|
|
### Get default ACL access
|
|
|
|
Gets the default access behaviour for the different ACL types.
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "getDefaultACLAccess",
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec getDefaultACLAccess
|
|
```
|
|
|
|
## Create Client
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "createClient",
|
|
"username": "new username",
|
|
"password": "new password",
|
|
"clientid": "", # Optional
|
|
"textname": "", # Optional
|
|
"textdescription": "", # Optional
|
|
"groups": [
|
|
{ "groupname": "group", "priority": 1 }
|
|
], # Optional, groups must exist
|
|
"roles": [
|
|
{ "rolename": "role", "priority": -1 }
|
|
] # Optional, roles must exist
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec createClient username password
|
|
```
|
|
|
|
## Delete Client
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "deleteClient",
|
|
"username": "username to delete"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec deleteClient username
|
|
```
|
|
|
|
## Enable Client
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "enableClient",
|
|
"username": "username to enable"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec enableClient username
|
|
```
|
|
|
|
## Disable Client
|
|
|
|
Stop a client from being able to log in, and kick any clients with matching
|
|
username that are currently connected.
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "disableClient",
|
|
"username": "username to disable"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec disableClient username
|
|
```
|
|
|
|
## Get Client
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "getClient",
|
|
"username": "required username"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec getClient username
|
|
```
|
|
|
|
## List Clients
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "listClients",
|
|
"verbose": false,
|
|
"count": -1, # -1 for all, or a positive integer for a limited count
|
|
"offset": 0 # Where in the list to start
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec listClients 10 20
|
|
```
|
|
|
|
## Modify Existing Client
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "modifyClient",
|
|
"username": "username to modify"
|
|
"textname": "", # Optional
|
|
"textdescription": "", # Optional
|
|
"roles": [
|
|
{ "rolename": "role", "priority": 1 }
|
|
], # Optional
|
|
"groups": [
|
|
{ "groupname": "group", "priority": 1 }
|
|
], # Optional
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Modifying clients isn't currently possible with mosquitto_ctrl.
|
|
|
|
## Set Client Password
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "setClientPassword",
|
|
"username": "username to change",
|
|
"password": "new password"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec setClientPassword username password
|
|
```
|
|
|
|
## Add Client Role
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "addClientRole",
|
|
"username": "client to add role to",
|
|
"rolename": "role to add",
|
|
"priority": -1 # Optional priority
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec addClientRole username rolename
|
|
```
|
|
|
|
## Remove Client Role
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "removeClientRole",
|
|
"username": "client to remove role from",
|
|
"rolename": "role to remove"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec removeClientRole username rolename
|
|
```
|
|
|
|
## Add Client to a Group
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "addGroupClient",
|
|
"groupname": "group to add client to",
|
|
"username": "client to add to group",
|
|
"priority": -1 # Priority of the group for the client
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec addGroupClient groupname username
|
|
```
|
|
|
|
## Create Group
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "createGroup",
|
|
"groupname": "new group",
|
|
"roles": [
|
|
{ "rolename": "role", "priority": 1 }
|
|
] # Optional, roles must exist
|
|
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec createGroup groupname
|
|
```
|
|
|
|
## Delete Group
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "deleteGroup",
|
|
"groupname: "group to delete"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec deleteGroup groupname
|
|
```
|
|
|
|
## Get Group
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "getGroup",
|
|
"groupname: "group to get"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec getGroup groupname
|
|
```
|
|
|
|
## List Groups
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "listGroups",
|
|
"verbose": false,
|
|
"count": -1, # -1 for all, or a positive integer for a limited count
|
|
"offset": 0 # Where in the list to start
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec listGroups
|
|
```
|
|
|
|
## Modify Group
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "modifyGroup",
|
|
"groupname": "group to modify",
|
|
"textname": "", # Optional
|
|
"textdescription": "", # Optional
|
|
"roles": [
|
|
{ "rolename": "role", "priority": 1 }
|
|
], # Optional
|
|
"clients": [
|
|
{ "username": "client", "priority": 1 }
|
|
] # Optional
|
|
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Modifying groups isn't currently possible with mosquitto_ctrl.
|
|
|
|
## Remove Client from a Group
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "removeGroupClient",
|
|
"groupname": "group to remove client from",
|
|
"username": "client to remove from group"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec removeGroupClient groupname username
|
|
```
|
|
|
|
## Add Group Role
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "addGroupRole",
|
|
"groupname": "group to add role to",
|
|
"rolename": "role to add",
|
|
"priority": -1 # Optional priority
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec addGroupRole groupname rolename
|
|
```
|
|
|
|
## Remove Group Role
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "removeGroupRole",
|
|
"groupname": "group",
|
|
"rolename": "role"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec removeGroupRole groupname rolename
|
|
```
|
|
|
|
## Set Group for Anonymous Clients
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "setAnonymousGroup",
|
|
"groupname": "group"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec setAnonymousGroup groupname
|
|
```
|
|
|
|
## Get Group for Anonymous Clients
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "getAnonymousGroup",
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec getAnonymousGroup
|
|
```
|
|
|
|
## Create Role
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "createRole",
|
|
"rolename": "new role",
|
|
"textname": "", # Optional
|
|
"textdescription": "", # Optional
|
|
"acls": [
|
|
{ "acltype": "subscribePattern", "topic": "topic/#", "priority": -1, "allow": true}
|
|
] # Optional
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec createRole rolename
|
|
```
|
|
|
|
## Get Role
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "getRole",
|
|
"rolename": "role",
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec getRole rolename
|
|
```
|
|
|
|
## List Roles
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "listRoles",
|
|
"verbose": false,
|
|
"count": -1, # -1 for all, or a positive integer for a limited count
|
|
"offset": 0 # Where in the list to start
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec listRoles
|
|
```
|
|
|
|
## Modify Role
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "modifyRole",
|
|
"rolename": "role to modify"
|
|
"textname": "", # Optional
|
|
"textdescription": "", # Optional
|
|
"acls": [
|
|
{ "acltype": "subscribePattern", "topic": "topic/#", "priority": -1, "allow": true }
|
|
] # Optional
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Modifying roles isn't currently possible with mosquitto_ctrl.
|
|
|
|
## Delete Role
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "deleteRole",
|
|
"rolename": "role"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec deleteRole rolename
|
|
```
|
|
|
|
## Add Role ACL
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "addRoleACL",
|
|
"acltype": "subscribePattern",
|
|
"topic": "topic/#",
|
|
"priority": -1,
|
|
"allow": true
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec addRoleACL rolename subscribeLiteral topic/# deny
|
|
```
|
|
|
|
## Remove Role ACL
|
|
|
|
Command:
|
|
```
|
|
{
|
|
"commands":[
|
|
{
|
|
"command": "removeRoleACL",
|
|
"acltype": "subscribePattern",
|
|
"topic": "topic/#"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
mosquitto_ctrl example:
|
|
```
|
|
mosquitto_ctrl dynsec removeRoleACL rolename subscribeLiteral topic/#
|
|
```
|