Broker Control 2.8.0 documentation

Broker Control 2.8.0

application/json

The broker control API gives information about listeners and plugins using the listListeners or listPluginscommand. A broker API request can be published to $CONTROL/broker/v1 and the related response message will be published to $CONTROL/broker/v1/response.

To enable this API add enable_control_api true to your mosquitto.conf.

Operations

PUB $CONTROL/broker/v1
Accepts the following message:
Request including the commands to be executedcontrolRequest
object
uid: controlRequestPayload
array<object anyOf>
object anyOf
restricted any
listListeners request

command
required
string
Command describing the action the broker should process.

Allowed values:
"listListeners"
"listPlugins"
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
Additional properties are allowed.
Additional properties are NOT allowed.
Examples
#1 Example - listListeners
{ "commands": [ { "command": "listListeners", "correlationData": "716cc776-d044-4772-b991-d9b55e2e034c" } ] }

#2 Example - listPlugins
{ "commands": [ { "command": "listPlugins", "correlationData": "716cc776-d044-4772-b991-d9b55e2e034c" } ] }
SUB $CONTROL/broker/v1/response
Accepts the following message:
Response including the responses of the command requestscontrolResponse
object
uid: controlResponsePayload
array<object anyOf>
object anyOf
restricted any
listListeners response

command
required
string
Command which describes the action processed by the plugin.

Allowed values:
"listListeners"
required
object
Specified if request has been processed successfully

required
array<object>
id
required
integer
Numeric identifier of the listener.

port
required
integer
Port the listener is bound to.

protocol
required
string
Describes whether the listener accepts pure mqtt or mqtt over websocket connections.

Allowed values:
"mqtt"
"mqtt+websockets"
bind-address
string
IP address the listener might be bound to. If the listener is not bound to an address this field is not set and the broker is bound to all interfaces.

socket-path
string
File path to a UNIX socket the listener is bound to.

tls
boolean
require-certificate
boolean
If this is set to true, the listener requires client certificate for authentication.

Additional properties are allowed.
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
restricted any
listPlugins response

command
required
string
Command which describes the action processed by the plugin.

Allowed values:
"listPlugins"
required
object
Specified if request has been processed successfully

required
array<object>
name
string
Name of the plugin, used when loaded by the broker.

version
string
Version of the plugin. Provided if specified during the plugin initialization.

port
integer
Port of the listener a plugin might use.

array<string>
List of $CONTROL topics the plugin handles.

Items:
string
Control topics handling plugin specific commands.

Examples values:
"$CONTROL/dynamic-security/v1"
Additional properties are allowed.
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
restricted any
error response

command
required
string
Command which describes the action processed by the plugin.

Allowed values:
"listListeners"
error
required
string
Examples values:
"Unknown command"
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
Additional properties are allowed.
Additional properties are NOT allowed.
Examples
#1 Example - listListeners
{ "responses": [ { "command": "listListeners", "data": { "listeners": [ { "id": 1, "port": 1883, "protocol": "mqtt", "tls": false }, { "id": 2, "port": 8883, "protocol": "mqtt", "tls": true, "require-certificate": true }, { "id": 3, "port": 8090, "protocol": "mqtt+websockets", "tls": true, "require-certificate": true } ] }, "correlationData": "716cc776-d044-4772-b991-d9b55e2e034c" } ] }

#2 Example - listPlugins
{ "responses": [ { "command": "listPlugins", "data": { "plugins": [ { "name": "dynamic-security", "control-endpoints": [ "$CONTROL/dynamic-security/v1" ] }, { "name": "inspect", "version": "1.0", "control-endpoints": [ "$CONTROL/cedalo/inspect/v1" ] }, { "name": "client-control", "control-endpoints": [ "$CONTROL/cedalo/client-control/v1" ] }, { "name": "certificate-management", "control-endpoints": [ "$CONTROL/certificate-management/v1" ] } ] }, "correlationData": "716cc776-d044-4772-b991-d9b55e2e034c" } ] }

#3 Example - error
Example of an error response message.
{ "responses": [ { "command": "listListeners", "error": "Error message", "correlationData": "716cc776-d044-4772-b991-d9b55e2e034c" } ] }

Messages

#1Request including the commands to be executedcontrolRequest
object
uid: controlRequestPayload
array<object anyOf>
object anyOf
restricted any
listListeners request

command
required
string
Command describing the action the broker should process.

Allowed values:
"listListeners"
"listPlugins"
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
Additional properties are allowed.
Additional properties are NOT allowed.
#2Response including the responses of the command requestscontrolResponse
object
uid: controlResponsePayload
array<object anyOf>
object anyOf
restricted any
listListeners response

command
required
string
Command which describes the action processed by the plugin.

Allowed values:
"listListeners"
required
object
Specified if request has been processed successfully

required
array<object>
id
required
integer
Numeric identifier of the listener.

port
required
integer
Port the listener is bound to.

protocol
required
string
Describes whether the listener accepts pure mqtt or mqtt over websocket connections.

Allowed values:
"mqtt"
"mqtt+websockets"
bind-address
string
IP address the listener might be bound to. If the listener is not bound to an address this field is not set and the broker is bound to all interfaces.

socket-path
string
File path to a UNIX socket the listener is bound to.

tls
boolean
require-certificate
boolean
If this is set to true, the listener requires client certificate for authentication.

Additional properties are allowed.
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
restricted any
listPlugins response

command
required
string
Command which describes the action processed by the plugin.

Allowed values:
"listPlugins"
required
object
Specified if request has been processed successfully

required
array<object>
name
string
Name of the plugin, used when loaded by the broker.

version
string
Version of the plugin. Provided if specified during the plugin initialization.

port
integer
Port of the listener a plugin might use.

array<string>
List of $CONTROL topics the plugin handles.

Items:
string
Control topics handling plugin specific commands.

Examples values:
"$CONTROL/dynamic-security/v1"
Additional properties are allowed.
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
restricted any
error response

command
required
string
Command which describes the action processed by the plugin.

Allowed values:
"listListeners"
error
required
string
Examples values:
"Unknown command"
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
Additional properties are allowed.
Additional properties are NOT allowed.

Schemas

object
uid: controlRequestPayload
array<object anyOf>
object anyOf
restricted any
listListeners request

command
required
string
Command describing the action the broker should process.

Allowed values:
"listListeners"
"listPlugins"
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
Additional properties are allowed.
Additional properties are NOT allowed.
object
uid: controlResponsePayload
array<object anyOf>
object anyOf
restricted any
listListeners response

command
required
string
Command which describes the action processed by the plugin.

Allowed values:
"listListeners"
required
object
Specified if request has been processed successfully

required
array<object>
id
required
integer
Numeric identifier of the listener.

port
required
integer
Port the listener is bound to.

protocol
required
string
Describes whether the listener accepts pure mqtt or mqtt over websocket connections.

Allowed values:
"mqtt"
"mqtt+websockets"
bind-address
string
IP address the listener might be bound to. If the listener is not bound to an address this field is not set and the broker is bound to all interfaces.

socket-path
string
File path to a UNIX socket the listener is bound to.

tls
boolean
require-certificate
boolean
If this is set to true, the listener requires client certificate for authentication.

Additional properties are allowed.
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
restricted any
listPlugins response

command
required
string
Command which describes the action processed by the plugin.

Allowed values:
"listPlugins"
required
object
Specified if request has been processed successfully

required
array<object>
name
string
Name of the plugin, used when loaded by the broker.

version
string
Version of the plugin. Provided if specified during the plugin initialization.

port
integer
Port of the listener a plugin might use.

array<string>
List of $CONTROL topics the plugin handles.

Items:
string
Control topics handling plugin specific commands.

Examples values:
"$CONTROL/dynamic-security/v1"
Additional properties are allowed.
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
restricted any
error response

command
required
string
Command which describes the action processed by the plugin.

Allowed values:
"listListeners"
error
required
string
Examples values:
"Unknown command"
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"
Additional properties are allowed.
Additional properties are NOT allowed.
correlationData
string
uid: correlationData
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.

Examples values:
"716cc776-d044-4772-b991-d9b55e2e034c"

Broker Control 2.8.0

Operations

PUB $CONTROL/broker/v1

Examples

#1 Example - listListeners

#2 Example - listPlugins

SUB $CONTROL/broker/v1/response

Examples

#1 Example - listListeners

#2 Example - listPlugins

#3 Example - error

Messages

Schemas