This document describes the topic based mechanism for controlling high availability clusters in Mosquitto.
JSON commands are published to the topic $CONTROL/cedalo/ha/v1. Responses will be published to $CONTROL/cedalo/ha/v1/response.
The HA plugin also integrates the Dynamic Security plugin for access control.
Accepts the following message:
createCluster request. Create a cluster.
Configure the first node in a cluster, possibly with extra nodes.
The dynamic security credentials stored on the current node will be propagated to other nodes.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
Tells the node receiving this command, which address he is assigned to.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
joinCluster request. Join a cluster.
Join a node to an existing cluster.
The dynamic security credentials stored on the current node will be propagated to other nodes.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
Tells the node receiving this command, which address he is assigned to.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
addNode request. Inform the cluster about a new node.
joinCluster tells a node to become part of a cluster, addNode
tells the cluster a new node is joining. Both should be used
when a new node is added. It does not matter in which order
they are carried out.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
removeNode request. Remove a node from the cluster.
Remove a node from an existing cluster. This should be sent to the cluster leader and will remove the node from the cluster configuration, and inform the node that it is no longer part of the cluster. It is the preferred method of removing a node.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
leaveCluster request. Leave a cluster.
Remove a node from an existing cluster. This is a fallback command for a node that has been removed from the cluster, but is not aware that it has been removed. This could happen if the node was offline when it was removed, for example. The command should be sent to the node that is to leave the cluster, not the cluster leader.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
deleteCluster request. Delete the cluster.
Removes cluster configuration from all nodes.
clustername currently has no purpose other than being a human
friendly identifier.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
getCluster request. Get information about the current cluster.
Get information about the current cluster configuration.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
getRaftStatus request. Get information about the current cluster status.
Get information about the current cluster status, like synchronization and leader/follower state.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
isLeader request. Ask the current node if he is the cluster leader.
Command to request if the current cluster node is the current cluster leader.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
setLeader request. Promote a specific node to be the cluster leader.
Promote a node to be the cluster leader. This should be sent to the cluster leader.
clustername currently has no purpose other than being a human
friendly identifier.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
Additional properties are NOT allowed.
{
"commands": [
{
"command": "createCluster",
"clustername": "name",
"nodes": [
{
"address": "192.168.1.1",
"port": 7000,
"nodeid": 1,
"mynode": true
},
{
"address": "192.168.1.2",
"port": 7000,
"nodeid": 2
},
{
"address": "192.168.1.3",
"port": 7000,
"nodeid": 3
}
]
}
]
}
{
"commands": [
{
"command": "joinCluster",
"clustername": "name",
"nodes": [
{
"address": "192.168.1.1",
"port": 7000,
"nodeid": 1,
"mynode": true
},
{
"address": "192.168.1.2",
"port": 7000,
"nodeid": 2
},
{
"address": "192.168.1.3",
"port": 7000,
"nodeid": 3
}
]
}
]
}
{
"commands": [
{
"command": "addNode",
"clustername": "test",
"address": "192.168.1.4",
"port": 7000,
"nodeid": 4
}
]
}
{
"commands": [
{
"command": "removeNode",
"clustername": "test",
"address": "192.168.1.4",
"port": 7000,
"nodeid": 4
}
]
}
{
"commands": [
{
"command": "leaveCluster",
"clustername": "test",
"address": "192.168.1.4",
"port": 7000,
"nodeid": 4
}
]
}
{
"commands": [
{
"command": "deleteCluster",
"clustername": "test"
}
]
}
{
"commands": [
{
"command": "getCluster"
}
]
}
{
"commands": [
{
"command": "getRaftStatus"
}
]
}
{
"commands": [
{
"command": "isLeader"
}
]
}
{
"commands": [
{
"command": "setLeader",
"nodeid": 4
}
]
}
Accepts the following message:
Successfull command execution response
Command which describes the action processed by the plugin.
getRaftStatus response
IP Address of the cluster node
Unique identifier of the cluster node.
0 RAFT_STANDBY: Replicate log, does not participate in quorum.
1 RAFT_VOTER: Replicate log, does participate in quorum.
2 RAFT_SPARE: Does not replicate log, or participate in quorum.
Highest consensus log entry known to be committed.
Highest consensus log entry applied to the internal finite-state machine.
Highest consensus log entry persisted on disk.
Latest term server has seen.
Possible values are
Unavailable 0 (typically not part of a cluster),
Follower 1 (received updates by the leader),
Candidate 2 (state during the election/voting process),
Leader 3 (cluster leader syncing current followers).
Cluster sync mode. dynsec is an active/active high availability cluster.
Current cluster status. Only valid from a leader, a follower will return undefined.
stable means that the cluster has sufficient voting nodes in contact with the leader
to be able to suffer the loss of at least one node without issue.
degraded means that the cluster has the minimum number of voting nodes in contact
with the leader, and hence is at risk of going offline if a single node disconnects.
offline means that the cluster does not have a majority and is offline.
Additional properties are allowed.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Error response
Command which describes the action processed by the plugin.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are allowed.
Additional properties are NOT allowed.
{
"responses": [
{
"command": "createCluster",
"correlationData": "1234-request"
}
]
}
{
"responses": [
{
"command": "removeNode",
"error": "This broker is not the cluster leader.",
"correlationData": "1234-request"
}
]
}
createCluster request. Create a cluster.
Configure the first node in a cluster, possibly with extra nodes.
The dynamic security credentials stored on the current node will be propagated to other nodes.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
Tells the node receiving this command, which address he is assigned to.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
joinCluster request. Join a cluster.
Join a node to an existing cluster.
The dynamic security credentials stored on the current node will be propagated to other nodes.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
Tells the node receiving this command, which address he is assigned to.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
addNode request. Inform the cluster about a new node.
joinCluster tells a node to become part of a cluster, addNode
tells the cluster a new node is joining. Both should be used
when a new node is added. It does not matter in which order
they are carried out.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
removeNode request. Remove a node from the cluster.
Remove a node from an existing cluster. This should be sent to the cluster leader and will remove the node from the cluster configuration, and inform the node that it is no longer part of the cluster. It is the preferred method of removing a node.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
leaveCluster request. Leave a cluster.
Remove a node from an existing cluster. This is a fallback command for a node that has been removed from the cluster, but is not aware that it has been removed. This could happen if the node was offline when it was removed, for example. The command should be sent to the node that is to leave the cluster, not the cluster leader.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
deleteCluster request. Delete the cluster.
Removes cluster configuration from all nodes.
clustername currently has no purpose other than being a human
friendly identifier.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
getCluster request. Get information about the current cluster.
Get information about the current cluster configuration.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
getRaftStatus request. Get information about the current cluster status.
Get information about the current cluster status, like synchronization and leader/follower state.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
isLeader request. Ask the current node if he is the cluster leader.
Command to request if the current cluster node is the current cluster leader.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
setLeader request. Promote a specific node to be the cluster leader.
Promote a node to be the cluster leader. This should be sent to the cluster leader.
clustername currently has no purpose other than being a human
friendly identifier.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
Additional properties are NOT allowed.
Successfull command execution response
Command which describes the action processed by the plugin.
getRaftStatus response
IP Address of the cluster node
Unique identifier of the cluster node.
0 RAFT_STANDBY: Replicate log, does not participate in quorum.
1 RAFT_VOTER: Replicate log, does participate in quorum.
2 RAFT_SPARE: Does not replicate log, or participate in quorum.
Highest consensus log entry known to be committed.
Highest consensus log entry applied to the internal finite-state machine.
Highest consensus log entry persisted on disk.
Latest term server has seen.
Possible values are
Unavailable 0 (typically not part of a cluster),
Follower 1 (received updates by the leader),
Candidate 2 (state during the election/voting process),
Leader 3 (cluster leader syncing current followers).
Cluster sync mode. dynsec is an active/active high availability cluster.
Current cluster status. Only valid from a leader, a follower will return undefined.
stable means that the cluster has sufficient voting nodes in contact with the leader
to be able to suffer the loss of at least one node without issue.
degraded means that the cluster has the minimum number of voting nodes in contact
with the leader, and hence is at risk of going offline if a single node disconnects.
offline means that the cluster does not have a majority and is offline.
Additional properties are allowed.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Error response
Command which describes the action processed by the plugin.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are allowed.
Additional properties are NOT allowed.
createCluster request. Create a cluster.
Configure the first node in a cluster, possibly with extra nodes.
The dynamic security credentials stored on the current node will be propagated to other nodes.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
Tells the node receiving this command, which address he is assigned to.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
joinCluster request. Join a cluster.
Join a node to an existing cluster.
The dynamic security credentials stored on the current node will be propagated to other nodes.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
Tells the node receiving this command, which address he is assigned to.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
addNode request. Inform the cluster about a new node.
joinCluster tells a node to become part of a cluster, addNode
tells the cluster a new node is joining. Both should be used
when a new node is added. It does not matter in which order
they are carried out.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
removeNode request. Remove a node from the cluster.
Remove a node from an existing cluster. This should be sent to the cluster leader and will remove the node from the cluster configuration, and inform the node that it is no longer part of the cluster. It is the preferred method of removing a node.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
leaveCluster request. Leave a cluster.
Remove a node from an existing cluster. This is a fallback command for a node that has been removed from the cluster, but is not aware that it has been removed. This could happen if the node was offline when it was removed, for example. The command should be sent to the node that is to leave the cluster, not the cluster leader.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
deleteCluster request. Delete the cluster.
Removes cluster configuration from all nodes.
clustername currently has no purpose other than being a human
friendly identifier.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
getCluster request. Get information about the current cluster.
Get information about the current cluster configuration.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
getRaftStatus request. Get information about the current cluster status.
Get information about the current cluster status, like synchronization and leader/follower state.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
isLeader request. Ask the current node if he is the cluster leader.
Command to request if the current cluster node is the current cluster leader.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
setLeader request. Promote a specific node to be the cluster leader.
Promote a node to be the cluster leader. This should be sent to the cluster leader.
clustername currently has no purpose other than being a human
friendly identifier.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are NOT allowed.
Additional properties are NOT allowed.
Successfull command execution response
Command which describes the action processed by the plugin.
getRaftStatus response
IP Address of the cluster node
Unique identifier of the cluster node.
0 RAFT_STANDBY: Replicate log, does not participate in quorum.
1 RAFT_VOTER: Replicate log, does participate in quorum.
2 RAFT_SPARE: Does not replicate log, or participate in quorum.
Highest consensus log entry known to be committed.
Highest consensus log entry applied to the internal finite-state machine.
Highest consensus log entry persisted on disk.
Latest term server has seen.
Possible values are
Unavailable 0 (typically not part of a cluster),
Follower 1 (received updates by the leader),
Candidate 2 (state during the election/voting process),
Leader 3 (cluster leader syncing current followers).
Cluster sync mode. dynsec is an active/active high availability cluster.
Current cluster status. Only valid from a leader, a follower will return undefined.
stable means that the cluster has sufficient voting nodes in contact with the leader
to be able to suffer the loss of at least one node without issue.
degraded means that the cluster has the minimum number of voting nodes in contact
with the leader, and hence is at risk of going offline if a single node disconnects.
offline means that the cluster does not have a majority and is offline.
Additional properties are allowed.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Error response
Command which describes the action processed by the plugin.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.
Additional properties are allowed.
Additional properties are NOT allowed.
Command which describes the action processed by the plugin.
clustername currently has no purpose other than being a human
friendly identifier.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
Tells the node receiving this command, which address he is assigned to.
IP address or hostname of the cluster node.
Port used for the cluster communication, typically 7000.
Unique identifier of the cluster node.
This is an optional value to be able to identify the relation between request and response. The plugin will add the provided value in the response message.