{
"tags": [
{
"name": "Error Codes"
},
{
"name": "Metrics"
},
{
"name": "Nodes"
},
{
"name": "Clients"
},
{
"name": "Publish"
},
{
"name": "Subscriptions"
},
{
"name": "Topics"
},
{
"name": "Authentication"
},
{
"name": "Authorization"
},
{
"name": "Banned"
},
{
"name": "Bridges"
},
{
"name": "Connectors"
},
{
"name": "Rules"
},
{
"name": "Listeners"
},
{
"name": "Listener Authentication"
},
{
"name": "MQTT"
},
{
"name": "Retainer"
},
{
"name": "Auto Subscribe"
},
{
"name": "System Topics"
},
{
"name": "Configs"
},
{
"name": "Cluster"
},
{
"name": "Monitor"
},
{
"name": "Gateways"
},
{
"name": "Gateway Authentication"
},
{
"name": "Gateway Listeners"
},
{
"name": "LwM2M Gateways"
},
{
"name": "CoAP Gateways"
},
{
"name": "ExHook"
},
{
"name": "Plugins"
},
{
"name": "Alarms"
},
{
"name": "Slow Subscriptions"
},
{
"name": "Trace"
},
{
"name": "Dashboard"
},
{
"name": "API Keys"
},
{
"name": "Telemetry"
}
],
"components": {
"parameters": {
"api_key.name": {
"description": "^[A-Za-z]+[A-Za-z0-9-_]*$",
"example": "EMQX-API-KEY-1",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
"cluster.node": {
"description": "node name",
"example": "emqx2@127.0.0.1",
"in": "path",
"name": "node",
"required": true,
"schema": {
"type": "string"
}
},
"emqx_authz_api_mnesia.clientid": {
"description": "ClientID",
"example": "client1",
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
},
"emqx_authz_api_mnesia.username": {
"description": "Username",
"example": "user1",
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
},
"emqx_mgmt_api_nodes.node_name": {
"description": "Node name",
"example": "emqx@127.0.0.1",
"in": "path",
"name": "node",
"required": true,
"schema": {
"type": "string"
}
},
"emqx_mgmt_api_stats.aggregate": {
"description": "Calculation aggregate for all nodes",
"example": false,
"in": "query",
"name": "aggregate",
"required": false,
"schema": {
"type": "boolean"
}
},
"listeners.listener_id": {
"description": "Listener id",
"example": "tcp:demo",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
"plugins.name": {
"description": "^[A-Za-z]+[A-Za-z0-9-_.]*$",
"example": "emqx_plugin_template-5.0-rc.1",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
"public.limit": {
"description": "Results per page(max 1000)",
"example": 50,
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
"public.page": {
"description": "Page number of the results to fetch.",
"example": 1,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"minimum": 1,
"type": "integer"
}
},
"trace.bytes": {
"description": "Maximum number of bytes to store in request",
"in": "query",
"name": "bytes",
"required": false,
"schema": {
"default": 1000,
"type": "integer"
}
},
"trace.name": {
"description": "[a-zA-Z0-9-_]",
"example": "EMQX-TRACE-1",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
"trace.node": {
"description": "Node name",
"example": "emqx@127.0.0.1",
"in": "query",
"name": "node",
"required": false,
"schema": {
"type": "string"
}
},
"trace.position": {
"description": "Offset from the current trace position.",
"in": "query",
"name": "position",
"required": false,
"schema": {
"default": 0,
"type": "integer"
}
}
},
"schemas": {
"emqx_gateway_api.gateway_listener_overview": {
"properties": {
"id": {
"description": "Listener ID",
"type": "string"
},
"running": {
"description": "Listener Running status",
"type": "boolean"
},
"type": {
"description": "Listener Type",
"enum": [
"tcp",
"ssl",
"udp",
"dtls"
],
"type": "string"
}
},
"type": "object"
},
"emqx_rule_api_schema.ctx_unsub": {
"required": [
"event_type"
],
"properties": {
"event_type": {
"description": "Event Type",
"enum": [
"session_unsubscribed"
],
"type": "string"
},
"clientid": {
"description": "The Client ID",
"type": "string"
},
"username": {
"description": "The User Name",
"type": "string"
},
"payload": {
"description": "The Message Payload",
"type": "string"
},
"peerhost": {
"description": "The IP Address of the Peer Client",
"type": "string"
},
"topic": {
"description": "Message Topic",
"type": "string"
},
"publish_received_at": {
"description": "The Time that this Message is Received",
"type": "integer"
},
"qos": {
"description": "The Message QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"modules.rewrite": {
"required": [
"re",
"dest_topic",
"source_topic",
"action"
],
"properties": {
"action": {
"description": "Topic rewriting takes effect on the type of operation:
- `subscribe`: Rewrite topic when client do subscribe.
- `publish`: Rewrite topic when client do publish.
- `all`: Both",
"enum": [
"subscribe",
"publish",
"all"
],
"example": "publish",
"type": "string"
},
"source_topic": {
"description": "Source topic, specified by the client.",
"example": "x/#",
"type": "string"
},
"dest_topic": {
"description": "Destination topic.",
"example": "z/y/$1",
"type": "string"
},
"re": {
"description": "Regular expressions",
"example": "^x/y/(.+)$",
"type": "string"
}
},
"type": "object"
},
"authz.node_status": {
"properties": {
"node": {
"description": "Node name.",
"example": "emqx@127.0.0.1",
"type": "string"
},
"status": {
"description": "The status of the resource for each node.",
"enum": [
"connected",
"disconnected",
"connecting"
],
"type": "string"
}
},
"type": "object"
},
"emqx_mgmt_api_publish.publish_ok": {
"properties": {
"id": {
"description": "A globally unique message ID for correlation/tracing.",
"type": "string"
}
},
"type": "object"
},
"broker.listener_wss_opts": {
"properties": {
"cacertfile": {
"description": "
Trusted PEM format CA certificates bundle file.
The certificates in this file are used to verify the TLS peer's certificates.
Append new certificates to the file if new CAs are to be trusted.
There is no need to restart EMQX to have the updated file loaded, because
the system regularly checks if file has been updated (and reload).
NOTE: invalidating (deleting) a certificate from the file will not affect
already established connections.
",
"type": "string"
},
"certfile": {
"description": "
PEM format certificates chain file.
The certificates in this file should be in reversed order of the certificate
issue chain. That is, the host's certificate should be placed in the beginning
of the file, followed by the immediate issuer certificate and so on.
Although the root CA certificate is optional, it should be placed at the end of
the file if it is to be added.
",
"type": "string"
},
"keyfile": {
"description": "PEM format private key file. ",
"type": "string"
},
"verify": {
"default": "verify_none",
"description": "Enable or disable peer verification. ",
"enum": [
"verify_peer",
"verify_none"
],
"type": "string"
},
"reuse_sessions": {
"default": true,
"description": "Enable TLS session reuse. ",
"type": "boolean"
},
"depth": {
"default": 10,
"description": "
Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path.
So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly;
if 1 the path can be PEER, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
",
"type": "integer"
},
"password": {
"description": "
String containing the user's password.
Only used if the private key file is password-protected.
",
"example": "",
"format": "password",
"type": "string"
},
"versions": {
"default": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
],
"description": "
All TLS/DTLS versions to be supported.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
In case PSK cipher suites are intended, make sure to configure
['tlsv1.2', 'tlsv1.1'] here.
",
"items": {
"type": "string"
},
"type": "array"
},
"ciphers": {
"default": "",
"description": "
This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\" or
[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"].
Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.
The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.
NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
PSK cipher suites: \"RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA\"
",
"items": {
"type": "string"
},
"type": "array"
},
"user_lookup_fun": {
"default": "emqx_tls_psk:lookup",
"description": "EMQX-internal callback that is used to lookup pre-shared key (PSK) identity. ",
"type": "string"
},
"secure_renegotiate": {
"default": true,
"description": "
SSL parameter renegotiation is a feature that allows a client and a server
to renegotiate the parameters of the SSL connection on the fly.
RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation,
you drop support for the insecure renegotiation, prone to MitM attacks.
",
"type": "boolean"
},
"dhfile": {
"description": "
Path to a file containing PEM-encoded Diffie-Hellman parameters
to be used by the server if a cipher suite using Diffie-Hellman
key exchange is negotiated. If not specified, default parameters
are used.
NOTE: The dhfile option is not supported by TLS 1.3.
",
"type": "string"
},
"fail_if_no_peer_cert": {
"default": false,
"description": "
Used together with {verify, verify_peer} by an TLS/DTLS server.
If set to true, the server fails if the client does not have a
certificate to send, that is, sends an empty certificate.
If set to false, it fails only if the client sends an invalid
certificate (an empty certificate is considered valid).
",
"type": "boolean"
},
"honor_cipher_order": {
"default": true,
"description": "
An important security setting, it forces the cipher to be set based
on the server-specified order instead of the client-specified order,
hence enforcing the (usually more properly configured) security
ordering of the server administrator.
",
"type": "boolean"
},
"client_renegotiation": {
"default": true,
"description": "
In protocols that support client-initiated renegotiation,
the cost of resources of such an operation is higher for the server than the client.
This can act as a vector for denial of service attacks.
The SSL application already takes measures to counter-act such attempts,
but client-initiated renegotiation can be strictly disabled by setting this option to false.
The default value is true. Note that disabling renegotiation can result in
long-lived connections becoming unusable due to limits on
the number of messages the underlying cipher suite can encipher.
",
"type": "boolean"
},
"handshake_timeout": {
"default": "15s",
"description": "
Maximum time duration allowed for the handshake to complete
",
"example": "12m",
"type": "string"
}
},
"type": "object"
},
"broker.sysmon_os": {
"properties": {
"cpu_check_interval": {
"default": "60s",
"description": "The time interval for the periodic CPU check.",
"example": "12m",
"type": "string"
},
"cpu_high_watermark": {
"default": "80%",
"description": "The threshold, as percentage of system CPU load,
for how much system cpu can be used before the corresponding alarm is raised.",
"example": "12%",
"type": "number"
},
"cpu_low_watermark": {
"default": "60%",
"description": "The threshold, as percentage of system CPU load,
for how much system cpu can be used before the corresponding alarm is cleared.",
"example": "12%",
"type": "number"
},
"mem_check_interval": {
"default": "60s",
"description": "The time interval for the periodic memory check.",
"oneOf": [
{
"example": "12m",
"type": "string"
},
{
"enum": [
"disabled"
],
"type": "string"
}
]
},
"sysmem_high_watermark": {
"default": "70%",
"description": "The threshold, as percentage of system memory,
for how much system memory can be allocated before the corresponding alarm is raised.",
"example": "12%",
"type": "number"
},
"procmem_high_watermark": {
"default": "5%",
"description": "The threshold, as percentage of system memory,
for how much system memory can be allocated by one Erlang process before
the corresponding alarm is raised.",
"example": "12%",
"type": "number"
}
},
"type": "object"
},
"rule_engine.builtin_action_republish": {
"properties": {
"function": {
"description": "Republish the message as a new MQTT message",
"enum": [
"republish"
],
"type": "string"
},
"args": {
"default": {},
"$ref": "#/components/schemas/rule_engine.republish_args"
}
},
"type": "object"
},
"emqx_authn_schema.metrics": {
"properties": {
"nomatch": {
"description": "The number of times the instance was ignored when the required authentication information was not found in the current instance.",
"type": "integer"
},
"total": {
"description": "The total number of times the current instance was triggered.",
"type": "integer"
},
"success": {
"description": "The required authentication information is found in the current instance, and the instance returns authentication success.",
"type": "integer"
},
"failed": {
"description": "The required authentication information is found in the current instance, and the instance returns authentication failure.",
"type": "integer"
},
"rate": {
"description": "The total rate at which instances are triggered, times/second.",
"type": "number"
},
"rate_max": {
"description": "The highest trigger rate the instance has ever reached, times/second.",
"type": "number"
},
"rate_last5m": {
"description": "The average trigger rate of the instance within 5 minutes, times/second.",
"type": "number"
}
},
"type": "object"
},
"broker.sysmon": {
"properties": {
"vm": {
"$ref": "#/components/schemas/broker.sysmon_vm"
},
"os": {
"$ref": "#/components/schemas/broker.sysmon_os"
},
"top": {
"$ref": "#/components/schemas/broker.sysmon_top"
}
},
"type": "object"
},
"dashboard.http": {
"required": [
"bind",
"enable"
],
"properties": {
"enable": {
"default": true,
"description": "Ignore or enable this listener",
"type": "boolean"
},
"bind": {
"default": 18083,
"description": "Port without IP(18083) or port with specified IP(127.0.0.1:18083).",
"example": "0.0.0.0:18083",
"oneOf": [
{
"example": "127.0.0.1:80",
"type": "string"
},
{
"minimum": 0,
"type": "integer"
}
]
},
"num_acceptors": {
"default": 20,
"description": "Socket acceptor pool size for TCP protocols. Default is the number of schedulers online",
"type": "integer"
},
"max_connections": {
"default": 512,
"description": "Maximum number of simultaneous connections.",
"type": "integer"
},
"backlog": {
"default": 1024,
"description": "Defines the maximum length that the queue of pending connections can grow to.",
"type": "integer"
},
"send_timeout": {
"default": "10s",
"description": "Send timeout for the socket.",
"example": "12m",
"type": "string"
},
"inet6": {
"default": false,
"description": "Enable IPv6 support, default is false, which means IPv4 only.",
"type": "boolean"
},
"ipv6_v6only": {
"default": false,
"description": "Disable IPv4-to-IPv6 mapping for the listener.
The configuration is only valid when the inet6 is true.",
"type": "boolean"
}
},
"type": "object"
},
"emqx_gateway_api.update_exproto": {
"required": [
"handler",
"server"
],
"properties": {
"server": {
"description": "Configurations for starting the ConnectionAdapter service",
"$ref": "#/components/schemas/gateway.exproto_grpc_server"
},
"handler": {
"description": "Configurations for request to ConnectionHandler service",
"$ref": "#/components/schemas/gateway.exproto_grpc_handler"
},
"mountpoint": {
"default": "",
"description": " ",
"type": "string"
},
"enable": {
"default": true,
"description": "Whether to enable this gateway",
"type": "boolean"
},
"enable_stats": {
"default": true,
"description": "Whether to enable client process statistic",
"type": "boolean"
},
"idle_timeout": {
"default": "30s",
"description": "The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.",
"example": "12m",
"type": "string"
},
"clientinfo_override": {
"description": "ClientInfo override.",
"$ref": "#/components/schemas/gateway.clientinfo_override"
}
},
"type": "object"
},
"emqx_authn_api.request_user_create": {
"required": [
"password",
"user_id"
],
"properties": {
"user_id": {
"type": "string"
},
"password": {
"type": "string"
},
"is_superuser": {
"default": false,
"type": "boolean"
}
},
"type": "object"
},
"authn-mysql.authentication": {
"required": [
"database",
"server",
"query",
"backend",
"mechanism"
],
"properties": {
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"password_based"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"mysql"
],
"type": "string"
},
"password_hash_algorithm": {
"default": {
"name": "sha256",
"salt_position": "prefix"
},
"description": "Options for password hash verification.",
"oneOf": [
{
"$ref": "#/components/schemas/authn-hash.other_algorithms"
},
{
"$ref": "#/components/schemas/authn-hash.pbkdf2"
},
{
"$ref": "#/components/schemas/authn-hash.bcrypt"
}
]
},
"query": {
"description": "SQL used to query data for authentication, such as password hash.",
"type": "string"
},
"query_timeout": {
"default": "5s",
"description": "Timeout for the SQL query.",
"example": "32s",
"type": "string"
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
},
"server": {
"description": "
The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The MySQL default port 3306 is used if `[:Port]` is not specified.
",
"type": "string"
},
"database": {
"description": "Database name.",
"type": "string"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"username": {
"default": "root",
"description": "EMQX's username in the external database.",
"type": "string"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auto_reconnect": {
"default": true,
"deprecated": "since(\"v5.0.15\")",
"description": "Deprecated. Enable automatic reconnect to the database.",
"type": "boolean"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"emqx_gateway_api.update_mqttsn": {
"required": [
"gateway_id"
],
"properties": {
"gateway_id": {
"default": 1,
"description": "MQTT-SN Gateway ID.
When the broadcast option is enabled, the gateway will broadcast ADVERTISE message with this value",
"type": "integer"
},
"broadcast": {
"default": false,
"description": "Whether to periodically broadcast ADVERTISE messages",
"type": "boolean"
},
"enable_qos3": {
"default": true,
"description": "Allows connectionless clients to publish messages with a Qos of -1.
This feature is defined for very simple client implementations which do not support any other features except this one. There is no connection setup nor tear down, no registration nor subscription. The client just sends its 'PUBLISH' messages to a GW",
"type": "boolean"
},
"subs_resume": {
"default": false,
"description": "Whether to initiate all subscribed topic name registration messages to the client after the Session has been taken over by a new channel",
"type": "boolean"
},
"predefined": {
"default": "",
"description": "The pre-defined topic IDs and topic names.
A 'pre-defined' topic ID is a topic ID whose mapping to a topic name is known in advance by both the client's application and the gateway",
"items": {
"$ref": "#/components/schemas/gateway.mqttsn_predefined"
},
"type": "array"
},
"mountpoint": {
"default": "",
"description": " ",
"type": "string"
},
"enable": {
"default": true,
"description": "Whether to enable this gateway",
"type": "boolean"
},
"enable_stats": {
"default": true,
"description": "Whether to enable client process statistic",
"type": "boolean"
},
"idle_timeout": {
"default": "30s",
"description": "The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.",
"example": "12m",
"type": "string"
},
"clientinfo_override": {
"description": "ClientInfo override.",
"$ref": "#/components/schemas/gateway.clientinfo_override"
}
},
"type": "object"
},
"emqx_gateway_api.stomp": {
"properties": {
"name": {
"description": "Gateway Name",
"enum": [
"stomp"
],
"type": "string"
},
"frame": {
"$ref": "#/components/schemas/gateway.stomp_frame"
},
"mountpoint": {
"default": "",
"description": " ",
"type": "string"
},
"enable": {
"default": true,
"description": "Whether to enable this gateway",
"type": "boolean"
},
"enable_stats": {
"default": true,
"description": "Whether to enable client process statistic",
"type": "boolean"
},
"idle_timeout": {
"default": "30s",
"description": "The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.",
"example": "12m",
"type": "string"
},
"clientinfo_override": {
"description": "ClientInfo override.",
"$ref": "#/components/schemas/gateway.clientinfo_override"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"listeners": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.ssl_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.tcp_listener"
}
]
},
"type": "array"
}
},
"type": "object"
},
"emqx_authz_api_mnesia.rules_for_username": {
"required": [
"username"
],
"properties": {
"rules": {
"items": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rule_item"
},
"type": "array"
},
"username": {
"description": "Username",
"example": "user1",
"type": "string"
}
},
"type": "object"
},
"emqx_gateway_api_clients.exproto_client": {
"properties": {
"node": {
"description": "Name of the node to which the client is connected",
"type": "string"
},
"clientid": {
"description": "Client ID",
"type": "string"
},
"username": {
"description": "Username of client when connecting",
"type": "string"
},
"mountpoint": {
"description": "Topic mountpoint",
"type": "string"
},
"proto_name": {
"description": "Client protocol name",
"type": "string"
},
"proto_ver": {
"description": "Protocol version used by the client",
"type": "string"
},
"ip_address": {
"description": "Client's IP address",
"type": "string"
},
"port": {
"description": "Client's port",
"type": "integer"
},
"is_bridge": {
"description": "Indicates whether the client is connected via bridge",
"type": "boolean"
},
"connected_at": {
"description": "Client connection time",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"disconnected_at": {
"description": "Client offline time, This field is only valid and returned when connected is false",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"connected": {
"description": "Whether the client is connected",
"type": "boolean"
},
"keepalive": {
"description": "Keepalive time, with the unit of second",
"type": "integer"
},
"clean_start": {
"description": "Indicate whether the client is using a brand new session",
"type": "boolean"
},
"expiry_interval": {
"description": "Session expiration interval, with the unit of second",
"type": "integer"
},
"created_at": {
"description": "Session creation time",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"subscriptions_cnt": {
"description": "Number of subscriptions established by this client",
"type": "integer"
},
"subscriptions_max": {
"description": "Maximum number of subscriptions allowed by this client",
"type": "integer"
},
"inflight_cnt": {
"description": "Current length of inflight",
"type": "integer"
},
"inflight_max": {
"description": "Maximum length of inflight",
"type": "integer"
},
"mqueue_len": {
"description": "Current length of message queue",
"type": "integer"
},
"mqueue_max": {
"description": "Maximum length of message queue",
"type": "integer"
},
"mqueue_dropped": {
"description": "Number of messages dropped by the message queue due to exceeding the length",
"type": "integer"
},
"awaiting_rel_cnt": {
"description": "Number of awaiting acknowledge packet",
"type": "integer"
},
"awaiting_rel_max": {
"description": "Maximum allowed number of awaiting PUBREC packet",
"type": "integer"
},
"recv_oct": {
"description": "Number of bytes received",
"type": "integer"
},
"recv_cnt": {
"description": "Number of socket packets received",
"type": "integer"
},
"recv_pkt": {
"description": "Number of protocol packets received",
"type": "integer"
},
"recv_msg": {
"description": "Number of message packets received",
"type": "integer"
},
"send_oct": {
"description": "Number of bytes sent",
"type": "integer"
},
"send_cnt": {
"description": "Number of socket packets sent",
"type": "integer"
},
"send_pkt": {
"description": "Number of protocol packets sent",
"type": "integer"
},
"send_msg": {
"description": "Number of message packets sent",
"type": "integer"
},
"mailbox_len": {
"description": "Process mailbox size",
"type": "integer"
},
"heap_size": {
"description": "Process heap size with the unit of byte",
"type": "integer"
},
"reductions": {
"description": "Erlang reduction",
"type": "integer"
}
},
"type": "object"
},
"connector-mqtt.ingress": {
"properties": {
"remote": {
"description": "The configs about subscribing to the remote broker.",
"$ref": "#/components/schemas/connector-mqtt.ingress_remote"
},
"local": {
"description": "The configs about sending message to the local broker.",
"$ref": "#/components/schemas/connector-mqtt.ingress_local"
}
},
"type": "object"
},
"connector-mqtt.egress_local": {
"properties": {
"topic": {
"description": "The local topic to be forwarded to the remote broker",
"type": "string"
}
},
"type": "object"
},
"emqx_authz_api_schema.mongo_sharded": {
"required": [
"database",
"servers",
"collection",
"type"
],
"properties": {
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "mongodb",
"description": "Backend type.",
"enum": [
"mongodb"
],
"type": "string"
},
"collection": {
"description": "`MongoDB` collection containing the authorization data.",
"type": "string"
},
"filter": {
"default": {},
"description": "
Conditional expression that defines the filter condition in the query.
Filter supports the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
",
"example": {},
"type": "object"
},
"mongo_type": {
"default": "sharded",
"description": "Sharded cluster. Must be set to 'sharded' when MongoDB server is running in 'sharded' mode.",
"enum": [
"sharded"
],
"type": "string"
},
"servers": {
"description": "
A Node list for Cluster to connect to. The nodes should be separated with commas, such as: `Node[,Node].`
For each Node should be: The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The MongoDB default port 27017 is used if `[:Port]` is not specified.
",
"type": "string"
},
"w_mode": {
"default": "unsafe",
"description": "Write mode.",
"enum": [
"unsafe",
"safe"
],
"type": "string"
},
"srv_record": {
"default": false,
"description": "Use DNS SRV record.",
"type": "boolean"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"username": {
"description": "EMQX's username in the external database.",
"type": "string"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auth_source": {
"description": "Database name associated with the user's credentials.",
"type": "string"
},
"database": {
"description": "Database name.",
"type": "string"
},
"topology": {
"$ref": "#/components/schemas/emqx_connector_mongo.topology"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"emqx_conf_schema.cluster_etcd": {
"properties": {
"server": {
"description": "List of endpoint URLs of the etcd cluster",
"example": "item1,item2",
"readOnly": true,
"type": "string"
},
"prefix": {
"default": "emqxcl",
"description": "Key prefix used for EMQX service discovery.",
"readOnly": true,
"type": "string"
},
"node_ttl": {
"default": "1m",
"description": "Expiration time of the etcd key associated with the node.
It is refreshed automatically, as long as the node is alive.
",
"example": "12m",
"readOnly": true,
"type": "string"
},
"ssl": {
"description": "Options for the TLS connection to the etcd cluster.",
"readOnly": true,
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"broker.shared_subscription_group": {
"properties": {
"strategy": {
"default": "random",
"description": "Dispatch strategy for shared subscription.
- `random`: dispatch the message to a random selected subscriber
- `round_robin`: select the subscribers in a round-robin manner
- `round_robin_per_group`: select the subscribers in round-robin fashion within each shared subscriber group
- `sticky`: always use the last selected subscriber to dispatch,
until the subscriber disconnects.
- `hash`: select the subscribers by the hash of `clientIds`
- `local`: send to a random local subscriber. If local
subscriber was not found, send to a random subscriber cluster-wide
",
"enum": [
"random",
"round_robin",
"round_robin_per_group",
"sticky",
"local",
"hash_topic",
"hash_clientid"
],
"type": "string"
}
},
"type": "object"
},
"listeners.wss_required_bind": {
"required": [
"bind",
"id",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"wss"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"id": {
"description": "Listener id",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"bind": {
"default": 8084,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
},
"ssl_options": {
"$ref": "#/components/schemas/broker.listener_wss_opts"
},
"websocket": {
"$ref": "#/components/schemas/broker.ws_opts"
}
},
"type": "object"
},
"emqx_authz_api_schema.built_in_database": {
"required": [
"type"
],
"properties": {
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "built_in_database",
"description": "Backend type.",
"enum": [
"built_in_database"
],
"type": "string"
}
},
"type": "object"
},
"emqx_mgmt_api_stats.node_stats_data": {
"properties": {
"channels.count": {
"description": "sessions.count",
"example": 0,
"minimum": 0,
"type": "integer"
},
"channels.max": {
"description": "session.max",
"example": 0,
"minimum": 0,
"type": "integer"
},
"connections.count": {
"description": "Number of current connections",
"example": 0,
"minimum": 0,
"type": "integer"
},
"connections.max": {
"description": "Historical maximum number of connections",
"example": 0,
"minimum": 0,
"type": "integer"
},
"delayed.count": {
"description": "Number of delayed messages",
"example": 0,
"minimum": 0,
"type": "integer"
},
"delayed.max": {
"description": "Historical maximum number of delayed messages",
"example": 0,
"minimum": 0,
"type": "integer"
},
"live_connections.count": {
"description": "Number of current live connections",
"example": 0,
"minimum": 0,
"type": "integer"
},
"live_connections.max": {
"description": "Historical maximum number of live connections",
"example": 0,
"minimum": 0,
"type": "integer"
},
"retained.count": {
"description": "Number of currently retained messages",
"example": 0,
"minimum": 0,
"type": "integer"
},
"retained.max": {
"description": "Historical maximum number of retained messages",
"example": 0,
"minimum": 0,
"type": "integer"
},
"sessions.count": {
"description": "Number of current sessions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"sessions.max": {
"description": "Historical maximum number of sessions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"suboptions.count": {
"description": "subscriptions.count",
"example": 0,
"minimum": 0,
"type": "integer"
},
"suboptions.max": {
"description": "subscriptions.max",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscribers.count": {
"description": "Number of current subscribers",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscribers.max": {
"description": "Historical maximum number of subscribers",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscriptions.count": {
"description": "Number of current subscriptions, including shared subscriptions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscriptions.max": {
"description": "Historical maximum number of subscriptions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscriptions.shared.count": {
"description": "Number of current shared subscriptions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscriptions.shared.max": {
"description": "Historical maximum number of shared subscriptions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"topics.count": {
"description": "Number of current topics",
"example": 0,
"minimum": 0,
"type": "integer"
},
"topics.max": {
"description": "Historical maximum number of topics",
"example": 0,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"emqx_rule_api_schema.rule_info": {
"required": [
"sql",
"id"
],
"properties": {
"id": {
"description": "The ID of the rule",
"example": "293fb66f",
"type": "string"
},
"from": {
"description": "The topics of the rule",
"example": "t/#",
"items": {
"type": "string"
},
"type": "array"
},
"created_at": {
"description": "The created time of the rule",
"example": "2021-12-01T15:00:43.153+08:00",
"type": "string"
},
"name": {
"default": "",
"description": "The name of the rule",
"example": "foo",
"type": "string"
},
"sql": {
"description": "
SQL query to transform the messages.
Example: SELECT * FROM \"test/topic\" WHERE payload.x = 1
",
"example": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
"type": "string"
},
"actions": {
"default": "",
"description": "
A list of actions of the rule.
An action can be a string that refers to the channel ID of an EMQX bridge, or an object
that refers to a function.
There a some built-in functions like \"republish\" and \"console\", and we also support user
provided functions in the format: \"{module}:{function}\".
The actions in the list are executed sequentially.
This means that if one of the action is executing slowly, all the following actions will not
be executed until it returns.
If one of the action crashed, all other actions come after it will still be executed, in the
original order.
If there's any error when running an action, there will be an error message, and the 'failure'
counter of the function action or the bridge channel will increase.
",
"example": [
"webhook:my_webhook",
{
"args": {
"payload": "${payload}",
"topic": "t/1"
},
"function": "republish"
},
{
"function": "console"
}
],
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/rule_engine.user_provided_function"
},
{
"$ref": "#/components/schemas/rule_engine.builtin_action_console"
},
{
"$ref": "#/components/schemas/rule_engine.builtin_action_republish"
},
{
"type": "string"
}
]
},
"type": "array"
},
"enable": {
"default": true,
"description": "Enable or disable the rule",
"type": "boolean"
},
"description": {
"default": "",
"description": "The description of the rule",
"example": "Some description",
"type": "string"
},
"metadata": {
"description": "Rule metadata, do not change manually",
"example": {},
"type": "object"
}
},
"type": "object"
},
"rule_engine.republish_args": {
"required": [
"topic"
],
"properties": {
"topic": {
"description": "
The target topic of message to be re-published.
Template with variables is allowed, see description of the 'republish_args'.
",
"example": "a/1",
"type": "string"
},
"qos": {
"default": "${qos}",
"description": "
The qos of the message to be re-published.
Template with variables is allowed, see description of the 'republish_args'.
Defaults to ${qos}. If variable ${qos} is not found from the selected result of the rule,
0 is used.
",
"example": "${qos}",
"oneOf": [
{
"type": "string"
},
{
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
]
},
"retain": {
"default": "${retain}",
"description": "
The 'retain' flag of the message to be re-published.
Template with variables is allowed, see description of the 'republish_args'.
Defaults to ${retain}. If variable ${retain} is not found from the selected result
of the rule, false is used.
",
"example": "${retain}",
"oneOf": [
{
"type": "string"
},
{
"type": "boolean"
}
]
},
"payload": {
"default": "${payload}",
"description": "
The payload of the message to be re-published.
Template with variables is allowed, see description of the 'republish_args'.
Defaults to ${payload}. If variable ${payload} is not found from the selected result
of the rule, then the string \"undefined\" is used.
",
"example": "${payload}",
"type": "string"
},
"user_properties": {
"default": "${user_properties}",
"description": "
From which variable should the MQTT message's User-Property pairs be taken from.
The value must be a map.
You may configure it to ${pub_props.'User-Property'} or
use SELECT *,pub_props.'User-Property' as user_properties
to forward the original user properties to the republished message.
You may also call map_put function like
map_put('my-prop-name', 'my-prop-value', user_properties) as user_properties
to inject user properties.
NOTE: MQTT spec allows duplicated user property names, but EMQX Rule-Engine does not.
",
"example": "${pub_props.'User-Property'}",
"type": "string"
}
},
"type": "object"
},
"authz.node_metrics": {
"properties": {
"node": {
"description": "Node name.",
"example": "emqx@127.0.0.1",
"type": "string"
},
"metrics": {
"description": "The metrics of the resource.",
"$ref": "#/components/schemas/authz.metrics"
}
},
"type": "object"
},
"emqx_rule_api_schema.metrics": {
"properties": {
"matched": {
"description": "How much times the FROM clause of the SQL is matched.",
"minimum": 0,
"type": "integer"
},
"matched.rate": {
"description": "The rate of matched, times/second",
"type": "number"
},
"matched.rate.max": {
"description": "The max rate of matched, times/second",
"type": "number"
},
"matched.rate.last5m": {
"description": "The average rate of matched in last 5 minutes, times/second",
"type": "number"
},
"passed": {
"description": "How much times the SQL is passed",
"minimum": 0,
"type": "integer"
},
"failed": {
"description": "How much times the SQL is failed",
"minimum": 0,
"type": "integer"
},
"failed.exception": {
"description": "How much times the SQL is failed due to exceptions. This may because of a crash when calling a SQL function, or trying to do arithmetic operation on undefined variables",
"minimum": 0,
"type": "integer"
},
"failed.unknown": {
"description": "How much times the SQL is failed due to an unknown error.",
"minimum": 0,
"type": "integer"
},
"actions.total": {
"description": "How much times the actions are called by the rule. This value may several times of 'matched', depending on the number of the actions of the rule.",
"minimum": 0,
"type": "integer"
},
"actions.success": {
"description": "How much times the rule success to call the actions.",
"minimum": 0,
"type": "integer"
},
"actions.failed": {
"description": "How much times the rule failed to call the actions.",
"minimum": 0,
"type": "integer"
},
"actions.failed.out_of_service": {
"description": "How much times the rule failed to call actions due to the action is out of service. For example, a bridge is disabled or stopped.",
"minimum": 0,
"type": "integer"
},
"actions.failed.unknown": {
"description": "How much times the rule failed to call actions due to to an unknown error.",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"bridge.metrics": {
"properties": {
"dropped": {
"description": "Count of messages dropped.",
"type": "integer"
},
"dropped.other": {
"description": "Count of messages dropped due to other reasons.",
"type": "integer"
},
"dropped.queue_full": {
"description": "Count of messages dropped due to the queue is full.",
"type": "integer"
},
"dropped.resource_not_found": {
"description": "Count of messages dropped due to the resource is not found.",
"type": "integer"
},
"dropped.resource_stopped": {
"description": "Count of messages dropped due to the resource is stopped.",
"type": "integer"
},
"matched": {
"description": "Count of this bridge is matched and queried.",
"type": "integer"
},
"queuing": {
"description": "Count of messages that are currently queuing.",
"type": "integer"
},
"retried": {
"description": "Times of retried.",
"type": "integer"
},
"failed": {
"description": "Count of messages that sent failed.",
"type": "integer"
},
"inflight": {
"description": "Count of messages that were sent asynchronously but ACKs are not yet received.",
"type": "integer"
},
"success": {
"description": "Count of messages that sent successfully.",
"type": "integer"
},
"rate": {
"description": "The rate of matched, times/second",
"type": "number"
},
"rate_max": {
"description": "The max rate of matched, times/second",
"type": "number"
},
"rate_last5m": {
"description": "The average rate of matched in the last 5 minutes, times/second",
"type": "number"
},
"received": {
"description": "Count of messages that is received from the remote system.",
"type": "number"
}
},
"type": "object"
},
"emqx_rule_api_schema.ctx_acked": {
"required": [
"event_type"
],
"properties": {
"event_type": {
"description": "Event Type",
"enum": [
"message_acked"
],
"type": "string"
},
"id": {
"description": "Message ID",
"type": "string"
},
"from_clientid": {
"description": "The Client ID",
"type": "string"
},
"from_username": {
"description": "The User Name",
"type": "string"
},
"clientid": {
"description": "The Client ID",
"type": "string"
},
"username": {
"description": "The User Name",
"type": "string"
},
"payload": {
"description": "The Message Payload",
"type": "string"
},
"peerhost": {
"description": "The IP Address of the Peer Client",
"type": "string"
},
"topic": {
"description": "Message Topic",
"type": "string"
},
"publish_received_at": {
"description": "The Time that this Message is Received",
"type": "integer"
},
"qos": {
"description": "The Message QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"dashboard.error_code": {
"properties": {
"code": {
"description": "Code Name",
"type": "string"
},
"description": {
"description": "Description",
"type": "string"
}
},
"type": "object"
},
"listeners.wss_not_required_bind": {
"required": [
"id",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"wss"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"id": {
"description": "Listener id",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"bind": {
"default": 8084,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
},
"ssl_options": {
"$ref": "#/components/schemas/broker.listener_wss_opts"
},
"websocket": {
"$ref": "#/components/schemas/broker.ws_opts"
}
},
"type": "object"
},
"emqx_authz_api_schema.postgresql": {
"required": [
"database",
"server",
"query",
"type"
],
"properties": {
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "postgresql",
"description": "Backend type.",
"enum": [
"postgresql"
],
"type": "string"
},
"query": {
"description": "Database query used to retrieve authorization data.",
"type": "string"
},
"server": {
"description": "
The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The PostgreSQL default port 5432 is used if `[:Port]` is not specified.
",
"type": "string"
},
"database": {
"description": "Database name.",
"type": "string"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"username": {
"description": "EMQX's username in the external database.",
"type": "string"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auto_reconnect": {
"default": true,
"deprecated": "since(\"v5.0.15\")",
"description": "Deprecated. Enable automatic reconnect to the database.",
"type": "boolean"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"emqx_mgmt_api_metrics.aggregated_metrics": {
"properties": {
"actions.failure": {
"description": "Number of failure executions of the rule engine action",
"minimum": 0,
"type": "integer"
},
"actions.success": {
"description": "Number of successful executions of the rule engine action",
"minimum": 0,
"type": "integer"
},
"bytes.received": {
"description": "Number of bytes received ",
"minimum": 0,
"type": "integer"
},
"bytes.sent": {
"description": "Number of bytes sent on this connection",
"minimum": 0,
"type": "integer"
},
"client.auth.anonymous": {
"description": "Number of clients who log in anonymously",
"minimum": 0,
"type": "integer"
},
"client.authenticate": {
"description": "Number of client authentications",
"minimum": 0,
"type": "integer"
},
"client.check_authz": {
"description": "Number of Authorization rule checks",
"minimum": 0,
"type": "integer"
},
"client.connack": {
"description": "Number of CONNACK packet sent",
"minimum": 0,
"type": "integer"
},
"client.connect": {
"description": "Number of client connections",
"minimum": 0,
"type": "integer"
},
"client.connected": {
"description": "Number of successful client connections",
"minimum": 0,
"type": "integer"
},
"client.disconnected": {
"description": "Number of client disconnects",
"minimum": 0,
"type": "integer"
},
"client.subscribe": {
"description": "Number of client subscriptions",
"minimum": 0,
"type": "integer"
},
"client.unsubscribe": {
"description": "Number of client unsubscriptions",
"minimum": 0,
"type": "integer"
},
"delivery.dropped": {
"description": "Total number of discarded messages when sending",
"minimum": 0,
"type": "integer"
},
"delivery.dropped.expired": {
"description": "Number of messages dropped due to message expiration on sending",
"minimum": 0,
"type": "integer"
},
"delivery.dropped.no_local": {
"description": "Number of messages that were dropped due to the No Local subscription option when sending",
"minimum": 0,
"type": "integer"
},
"delivery.dropped.qos0_msg": {
"description": "Number of messages with QoS 0 that were dropped because the message queue was full when sending",
"minimum": 0,
"type": "integer"
},
"delivery.dropped.queue_full": {
"description": "Number of messages with a non-zero QoS that were dropped because the message queue was full when sending",
"minimum": 0,
"type": "integer"
},
"delivery.dropped.too_large": {
"description": "The number of messages that were dropped because the length exceeded the limit when sending",
"minimum": 0,
"type": "integer"
},
"messages.acked": {
"description": "Number of received PUBACK and PUBREC packet",
"minimum": 0,
"type": "integer"
},
"messages.delayed": {
"description": "Number of delay-published messages",
"minimum": 0,
"type": "integer"
},
"messages.delivered": {
"description": "Number of messages forwarded to the subscription process internally",
"minimum": 0,
"type": "integer"
},
"messages.dropped": {
"description": "Total number of messages dropped before forwarding to the subscription process",
"minimum": 0,
"type": "integer"
},
"messages.dropped.await_pubrel_timeout": {
"description": "Number of messages dropped due to waiting PUBREL timeout",
"minimum": 0,
"type": "integer"
},
"messages.dropped.no_subscribers": {
"description": "Number of messages dropped due to no subscribers",
"minimum": 0,
"type": "integer"
},
"messages.forward": {
"description": "Number of messages forwarded to other nodes",
"minimum": 0,
"type": "integer"
},
"messages.publish": {
"description": "Number of messages published in addition to system messages",
"minimum": 0,
"type": "integer"
},
"messages.qos0.received": {
"description": "Number of QoS 0 messages received from clients",
"minimum": 0,
"type": "integer"
},
"messages.qos0.sent": {
"description": "Number of QoS 0 messages sent to clients",
"minimum": 0,
"type": "integer"
},
"messages.qos1.received": {
"description": "Number of QoS 1 messages received from clients",
"minimum": 0,
"type": "integer"
},
"messages.qos1.sent": {
"description": "Number of QoS 1 messages sent to clients",
"minimum": 0,
"type": "integer"
},
"messages.qos2.received": {
"description": "Number of QoS 2 messages received from clients",
"minimum": 0,
"type": "integer"
},
"messages.qos2.sent": {
"description": "Number of QoS 2 messages sent to clients",
"minimum": 0,
"type": "integer"
},
"messages.received": {
"description": "Number of messages received from the client, equal to the sum of messages.qos0.received\fmessages.qos1.received and messages.qos2.received",
"minimum": 0,
"type": "integer"
},
"messages.retained": {
"description": "Number of retained messages",
"minimum": 0,
"type": "integer"
},
"messages.sent": {
"description": "Number of messages sent to the client, equal to the sum of messages.qos0.sent\fmessages.qos1.sent and messages.qos2.sent",
"minimum": 0,
"type": "integer"
},
"packets.auth.received": {
"description": "Number of received AUTH packet",
"minimum": 0,
"type": "integer"
},
"packets.auth.sent": {
"description": "Number of sent AUTH packet",
"minimum": 0,
"type": "integer"
},
"packets.connack.auth_error": {
"description": "Number of received CONNECT packet with failed authentication",
"minimum": 0,
"type": "integer"
},
"packets.connack.error": {
"description": "Number of received CONNECT packet with unsuccessful connections",
"minimum": 0,
"type": "integer"
},
"packets.connack.sent": {
"description": "Number of sent CONNACK packet",
"minimum": 0,
"type": "integer"
},
"packets.connect.received": {
"description": "Number of received CONNECT packet",
"minimum": 0,
"type": "integer"
},
"packets.disconnect.received": {
"description": "Number of received DISCONNECT packet",
"minimum": 0,
"type": "integer"
},
"packets.disconnect.sent": {
"description": "Number of sent DISCONNECT packet",
"minimum": 0,
"type": "integer"
},
"packets.pingreq.received": {
"description": "Number of received PINGREQ packet",
"minimum": 0,
"type": "integer"
},
"packets.pingresp.sent": {
"description": "Number of sent PUBRESP packet",
"minimum": 0,
"type": "integer"
},
"packets.puback.inuse": {
"description": "Number of received PUBACK packet with occupied identifiers",
"minimum": 0,
"type": "integer"
},
"packets.puback.missed": {
"description": "Number of received packet with identifiers.",
"minimum": 0,
"type": "integer"
},
"packets.puback.received": {
"description": "Number of received PUBACK packet",
"minimum": 0,
"type": "integer"
},
"packets.puback.sent": {
"description": "Number of sent PUBACK packet",
"minimum": 0,
"type": "integer"
},
"packets.pubcomp.inuse": {
"description": "Number of received PUBCOMP packet with occupied identifiers",
"minimum": 0,
"type": "integer"
},
"packets.pubcomp.missed": {
"description": "Number of missed PUBCOMP packet",
"minimum": 0,
"type": "integer"
},
"packets.pubcomp.received": {
"description": "Number of received PUBCOMP packet",
"minimum": 0,
"type": "integer"
},
"packets.pubcomp.sent": {
"description": "Number of sent PUBCOMP packet",
"minimum": 0,
"type": "integer"
},
"packets.publish.auth_error": {
"description": "Number of received PUBLISH packets with failed the Authorization check",
"minimum": 0,
"type": "integer"
},
"packets.publish.dropped": {
"description": "Number of messages discarded due to the receiving limit",
"minimum": 0,
"type": "integer"
},
"packets.publish.error": {
"description": "Number of received PUBLISH packet that cannot be published",
"minimum": 0,
"type": "integer"
},
"packets.publish.inuse": {
"description": "Number of received PUBLISH packet with occupied identifiers",
"minimum": 0,
"type": "integer"
},
"packets.publish.received": {
"description": "Number of received PUBLISH packet",
"minimum": 0,
"type": "integer"
},
"packets.publish.sent": {
"description": "Number of sent PUBLISH packet",
"minimum": 0,
"type": "integer"
},
"packets.pubrec.inuse": {
"description": "Number of received PUBREC packet with occupied identifiers",
"minimum": 0,
"type": "integer"
},
"packets.pubrec.missed": {
"description": "Number of received PUBREC packet with unknown identifiers",
"minimum": 0,
"type": "integer"
},
"packets.pubrec.received": {
"description": "Number of received PUBREC packet",
"minimum": 0,
"type": "integer"
},
"packets.pubrec.sent": {
"description": "Number of sent PUBREC packet",
"minimum": 0,
"type": "integer"
},
"packets.pubrel.missed": {
"description": "Number of received PUBREC packet with unknown identifiers",
"minimum": 0,
"type": "integer"
},
"packets.pubrel.received": {
"description": "Number of received PUBREL packet",
"minimum": 0,
"type": "integer"
},
"packets.pubrel.sent": {
"description": "Number of sent PUBREL packet",
"minimum": 0,
"type": "integer"
},
"packets.received": {
"description": "Number of received packet",
"minimum": 0,
"type": "integer"
},
"packets.sent": {
"description": "Number of sent packet",
"minimum": 0,
"type": "integer"
},
"packets.suback.sent": {
"description": "Number of sent SUBACK packet",
"minimum": 0,
"type": "integer"
},
"packets.subscribe.auth_error": {
"description": "Number of received SUBACK packet with failed Authorization check",
"minimum": 0,
"type": "integer"
},
"packets.subscribe.error": {
"description": "Number of received SUBSCRIBE packet with failed subscriptions",
"minimum": 0,
"type": "integer"
},
"packets.subscribe.received": {
"description": "Number of received SUBSCRIBE packet",
"minimum": 0,
"type": "integer"
},
"packets.unsuback.sent": {
"description": "Number of sent UNSUBACK packet",
"minimum": 0,
"type": "integer"
},
"packets.unsubscribe.error": {
"description": "Number of received UNSUBSCRIBE packet with failed unsubscriptions",
"minimum": 0,
"type": "integer"
},
"packets.unsubscribe.received": {
"description": "Number of received UNSUBSCRIBE packet",
"minimum": 0,
"type": "integer"
},
"rules.matched": {
"description": "Number of rule matched",
"minimum": 0,
"type": "integer"
},
"session.created": {
"description": "Number of sessions created",
"minimum": 0,
"type": "integer"
},
"session.discarded": {
"description": "Number of sessions dropped because Clean Session or Clean Start is true",
"minimum": 0,
"type": "integer"
},
"session.resumed": {
"description": "Number of sessions resumed because Clean Session or Clean Start is false",
"minimum": 0,
"type": "integer"
},
"session.takenover": {
"description": "Number of sessions takenover because Clean Session or Clean Start is false",
"minimum": 0,
"type": "integer"
},
"session.terminated": {
"description": "Number of terminated sessions",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"emqx_authz_api_schema.redis_cluster": {
"required": [
"servers",
"cmd",
"type"
],
"properties": {
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "redis",
"description": "Backend type.",
"enum": [
"redis"
],
"type": "string"
},
"cmd": {
"description": "Database query used to retrieve authorization data.",
"example": "HGETALL mqtt_authz",
"type": "string"
},
"servers": {
"description": "
A Node list for Cluster to connect to. The nodes should be separated with commas, such as: `Node[,Node].`
For each Node should be: The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The Redis default port 6379 is used if `[:Port]` is not specified.
",
"type": "string"
},
"redis_type": {
"default": "cluster",
"description": "Cluster mode. Must be set to 'cluster' when Redis server is running in clustered mode.",
"enum": [
"cluster"
],
"type": "string"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auto_reconnect": {
"default": true,
"deprecated": "since(\"v5.0.15\")",
"description": "Deprecated. Enable automatic reconnect to the database.",
"type": "boolean"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"connector-http.request": {
"properties": {
"method": {
"description": "HTTP method.",
"type": "string"
},
"path": {
"description": "URL path.",
"type": "string"
},
"body": {
"description": "HTTP request body.",
"type": "string"
},
"headers": {
"description": "List of HTTP headers.",
"example": {},
"type": "object"
},
"max_retries": {
"description": "Max retry times if error on sending request.",
"minimum": 0,
"type": "integer"
},
"request_timeout": {
"description": "HTTP request timeout.",
"example": "32s",
"type": "string"
}
},
"type": "object"
},
"emqx_mgmt_api_banned.ban": {
"required": [
"who",
"as"
],
"properties": {
"as": {
"description": "Ban method, which can be client ID, username or IP address.",
"enum": [
"clientid",
"username",
"peerhost"
],
"example": "username",
"type": "string"
},
"who": {
"description": "Ban object, specific client ID, username or IP address.",
"example": "Banned name",
"type": "string"
},
"by": {
"description": "Initiator of the ban.",
"example": "mgmt_api",
"type": "string"
},
"reason": {
"description": "Ban reason, record the reason why the current object was banned.",
"example": "Too many requests",
"type": "string"
},
"at": {
"description": "The start time of the ban, the format is rfc3339, the default is the time when the operation was initiated.",
"example": "2021-10-25T21:48:47+08:00",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"until": {
"description": "The end time of the ban, the format is rfc3339, the default is the time when the operation was initiated + 5 minutes.",
"example": "2021-10-25T21:53:47+08:00",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
}
},
"type": "object"
},
"bridge.node_status": {
"properties": {
"node": {
"description": "The node name.",
"example": "emqx@127.0.0.1",
"type": "string"
},
"status": {
"enum": [
"connected",
"disconnected",
"connecting"
],
"type": "string"
}
},
"type": "object"
},
"limiter.node_opts": {
"properties": {
"rate": {
"default": "infinity",
"description": "Rate for this bucket.",
"example": "10MB",
"type": "string"
},
"burst": {
"default": 0,
"description": "The burst, This value is based on rate.
This value + rate = the maximum limit that can be achieved when limiter burst.",
"example": "10MB",
"type": "string"
}
},
"type": "object"
},
"authz.node_error": {
"properties": {
"node": {
"description": "Node name.",
"example": "emqx@127.0.0.1",
"type": "string"
},
"error": {
"description": "The error of node.",
"type": "string"
}
},
"type": "object"
},
"api_key.app": {
"properties": {
"name": {
"description": "Unique and format by [a-zA-Z0-9-_]",
"example": "EMQX-API-KEY-1",
"type": "string"
},
"api_key": {
"description": "TODO:uses HMAC-SHA256 for signing.",
"example": "a4697a5c75a769f6",
"type": "string"
},
"api_secret": {
"description": "An API secret is a simple encrypted string that identifiesan application without any principal.They are useful for accessing public data anonymously,and are used to associate API requests.",
"example": "MzAyMjk3ODMwMDk0NjIzOTUxNjcwNzQ0NzQ3MTE2NDYyMDI",
"type": "string"
},
"expired_at": {
"default": "infinity",
"description": "No longer valid datetime",
"example": "2021-12-05T02:01:34.186Z",
"oneOf": [
{
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"created_at": {
"description": "ApiKey create datetime",
"example": "2021-12-01T00:00:00.000Z",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"desc": {
"example": "Note",
"type": "string"
},
"enable": {
"description": "Enable/Disable",
"type": "boolean"
},
"expired": {
"description": "Expired",
"type": "boolean"
}
},
"type": "object"
},
"emqx_mgmt_api_publish.publish_error": {
"properties": {
"reason_code": {
"description": "
The MQTT reason code, as the same ones used in PUBACK packet.
Currently supported codes are:
16(0x10): No matching subscribers;
131(0x81): Error happened when dispatching the message. e.g. during EMQX restart;
144(0x90): Topic name invalid;
151(0x97): Publish rate limited, or message size exceeded limit. The global size limit can be configured with mqtt.max_packet_size
NOTE: The message size is estimated with the received topic and payload size, meaning the actual size of serialized bytes (when sent to MQTT subscriber)
might be slightly over the limit.
",
"example": 16,
"type": "integer"
},
"message": {
"description": "Describes the failure reason in detail.",
"example": "no_matching_subscribers",
"type": "string"
}
},
"type": "object"
},
"broker.deflate_opts": {
"properties": {
"level": {
"description": "Compression level. ",
"enum": [
"none",
"default",
"best_compression",
"best_speed"
],
"type": "string"
},
"mem_level": {
"default": 8,
"description": "
Specifies the size of the compression state.
Lower values decrease memory usage per connection.
",
"maximum": 9,
"minimum": 1,
"type": "integer"
},
"strategy": {
"default": "default",
"description": "Specifies the compression strategy.",
"enum": [
"default",
"filtered",
"huffman_only",
"rle"
],
"type": "string"
},
"server_context_takeover": {
"default": "takeover",
"description": "Takeover means the compression state is retained between server messages. ",
"enum": [
"takeover",
"no_takeover"
],
"type": "string"
},
"client_context_takeover": {
"default": "takeover",
"description": "Takeover means the compression state is retained between client messages. ",
"enum": [
"takeover",
"no_takeover"
],
"type": "string"
},
"server_max_window_bits": {
"default": 15,
"description": "Specifies the size of the compression context for the server.",
"maximum": 15,
"minimum": 8,
"type": "integer"
},
"client_max_window_bits": {
"default": 15,
"description": "Specifies the size of the compression context for the client.",
"maximum": 15,
"minimum": 8,
"type": "integer"
}
},
"type": "object"
},
"broker.authz_cache": {
"required": [
"enable"
],
"properties": {
"enable": {
"default": true,
"description": "Enable or disable the authorization cache.",
"type": "boolean"
},
"max_size": {
"default": 32,
"description": "Maximum number of cached items.",
"maximum": 1048576,
"minimum": 1,
"type": "integer"
},
"ttl": {
"default": "1m",
"description": "Time to live for the cached data. ",
"example": "12m",
"type": "string"
}
},
"type": "object"
},
"broker.tcp_opts": {
"properties": {
"active_n": {
"default": 100,
"description": "
Specify the {active, N} option for this Socket.
See: https://erlang.org/doc/man/inet.html#setopts-2
",
"type": "integer"
},
"backlog": {
"default": 1024,
"description": "
TCP backlog defines the maximum length that the queue of
pending connections can grow to.
",
"minimum": 1,
"type": "integer"
},
"send_timeout": {
"default": "15s",
"description": "The TCP send timeout for the connections. ",
"example": "12m",
"type": "string"
},
"send_timeout_close": {
"default": true,
"description": "
Close the connection if send timeout.
",
"type": "boolean"
},
"recbuf": {
"description": "
The TCP receive buffer (OS kernel) for the connections.
",
"example": "2KB",
"type": "string"
},
"sndbuf": {
"description": "
The TCP send buffer (OS kernel) for the connections.
",
"example": "4KB",
"type": "string"
},
"buffer": {
"default": "4KB",
"description": "
The size of the user-space buffer used by the driver.
",
"example": "4KB",
"type": "string"
},
"high_watermark": {
"default": "1MB",
"description": "
The socket is set to a busy state when the amount of data queued internally
by the VM socket implementation reaches this limit.
",
"example": "32MB",
"type": "string"
},
"nodelay": {
"default": true,
"description": "
The TCP_NODELAY flag for the connections.
",
"type": "boolean"
},
"reuseaddr": {
"default": true,
"description": "
The SO_REUSEADDR flag for the connections.
",
"type": "boolean"
}
},
"type": "object"
},
"emqx_topic_metrics_api.reset": {
"required": [
"action"
],
"properties": {
"topic": {
"example": "testtopic/1",
"type": "string"
},
"action": {
"description": "Action. Only support reset",
"example": "reset",
"type": "string"
}
},
"type": "object"
},
"emqx_rule_api_schema.rule_metrics": {
"required": [
"id"
],
"properties": {
"id": {
"description": "The ID of the rule",
"example": "293fb66f",
"type": "string"
},
"metrics": {
"description": "The metrics of the rule",
"$ref": "#/components/schemas/emqx_rule_api_schema.metrics"
},
"node_metrics": {
"description": "The metrics of the rule for each node",
"items": {
"$ref": "#/components/schemas/emqx_rule_api_schema.node_metrics"
},
"type": "array"
}
},
"type": "object"
},
"emqx_gateway_api.update_stomp": {
"properties": {
"frame": {
"$ref": "#/components/schemas/gateway.stomp_frame"
},
"mountpoint": {
"default": "",
"description": " ",
"type": "string"
},
"enable": {
"default": true,
"description": "Whether to enable this gateway",
"type": "boolean"
},
"enable_stats": {
"default": true,
"description": "Whether to enable client process statistic",
"type": "boolean"
},
"idle_timeout": {
"default": "30s",
"description": "The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.",
"example": "12m",
"type": "string"
},
"clientinfo_override": {
"description": "ClientInfo override.",
"$ref": "#/components/schemas/gateway.clientinfo_override"
}
},
"type": "object"
},
"emqx_conf_schema.log_burst_limit": {
"properties": {
"enable": {
"default": true,
"description": "Enable log burst control feature.",
"type": "boolean"
},
"max_count": {
"default": 10000,
"description": "Maximum number of log events to handle within a `window_time` interval. After the limit is reached, successive events are dropped until the end of the `window_time`.",
"minimum": 1,
"type": "integer"
},
"window_time": {
"default": "1s",
"description": "See max_count.",
"example": "12m",
"type": "string"
}
},
"type": "object"
},
"connector-mqtt.egress_remote": {
"required": [
"topic"
],
"properties": {
"topic": {
"description": "
Forward to which topic of the remote broker.
Template with variables is allowed.
",
"type": "string"
},
"qos": {
"default": 1,
"description": "
The QoS of the MQTT message to be sent.
Template with variables is allowed.
",
"oneOf": [
{
"type": "string"
},
{
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
]
},
"retain": {
"default": false,
"description": "
The 'retain' flag of the MQTT message to be sent.
Template with variables is allowed.
",
"oneOf": [
{
"type": "string"
},
{
"type": "boolean"
}
]
},
"payload": {
"description": "
The payload of the MQTT message to be sent.
Template with variables is allowed.
",
"type": "string"
}
},
"type": "object"
},
"plugins.position": {
"properties": {
"position": {
"description": "
Enable auto-boot at position in the boot list, where Position could be
'front', 'rear', or 'before:other-vsn', 'after:other-vsn'
to specify a relative position.
",
"oneOf": [
{
"type": "string"
},
{
"enum": [
"rear"
],
"type": "string"
},
{
"enum": [
"front"
],
"type": "string"
}
]
}
},
"type": "object"
},
"bridge.node_metrics": {
"properties": {
"node": {
"description": "The node name.",
"example": "emqx@127.0.0.1",
"type": "string"
},
"metrics": {
"$ref": "#/components/schemas/bridge.metrics"
}
},
"type": "object"
},
"emqx_conf_schema.cluster": {
"properties": {
"name": {
"default": "emqxcl",
"description": "Human-friendly name of the EMQX cluster.",
"readOnly": true,
"type": "string"
},
"discovery_strategy": {
"default": "manual",
"description": "Service discovery method for the cluster nodes.",
"enum": [
"manual",
"static",
"mcast",
"dns",
"etcd",
"k8s"
],
"readOnly": true,
"type": "string"
},
"core_nodes": {
"default": "",
"description": "
List of core nodes that the replicant will connect to.
Note: this parameter only takes effect when the backend is set
to rlog and the role is set to replicant.
This value needs to be defined for manual or static cluster discovery mechanisms.
If an automatic cluster discovery mechanism is being used (such as etcd),
there is no need to set this value.
",
"example": "item1,item2",
"readOnly": true,
"type": "string"
},
"autoclean": {
"default": "5m",
"description": "Remove disconnected nodes from the cluster after this interval.",
"example": "12m",
"readOnly": true,
"type": "string"
},
"autoheal": {
"default": true,
"description": "If true, the node will try to heal network partitions automatically.",
"readOnly": true,
"type": "boolean"
},
"proto_dist": {
"default": "inet_tcp",
"description": "The Erlang distribution protocol for the cluster.",
"enum": [
"inet_tcp",
"inet6_tcp",
"inet_tls"
],
"readOnly": true,
"type": "string"
},
"static": {
"$ref": "#/components/schemas/emqx_conf_schema.cluster_static"
},
"mcast": {
"$ref": "#/components/schemas/emqx_conf_schema.cluster_mcast"
},
"dns": {
"$ref": "#/components/schemas/emqx_conf_schema.cluster_dns"
},
"etcd": {
"$ref": "#/components/schemas/emqx_conf_schema.cluster_etcd"
},
"k8s": {
"$ref": "#/components/schemas/emqx_conf_schema.cluster_k8s"
}
},
"type": "object"
},
"plugins.running_status": {
"properties": {
"node": {
"example": "emqx@127.0.0.1",
"type": "string"
},
"status": {
"description": "Install plugin status at runtime
1. running: plugin is running.
2. stopped: plugin is stopped.
",
"enum": [
"running",
"stopped"
],
"type": "string"
}
},
"type": "object"
},
"bridge_mqtt.creation_opts": {
"properties": {
"worker_pool_size": {
"default": 16,
"description": "The number of buffer workers. Only applicable for egress type bridges.
For bridges only have ingress direction data flow, it can be set to 0 otherwise must be greater than 0.",
"minimum": 0,
"type": "integer"
},
"health_check_interval": {
"default": "15s",
"description": "Health check interval.",
"example": "32s",
"type": "string"
},
"start_after_created": {
"default": "true",
"description": "Whether start the resource right after created.",
"type": "boolean"
},
"start_timeout": {
"default": "5s",
"description": "Time interval to wait for an auto-started resource to become healthy before responding resource creation requests.",
"example": "32s",
"type": "string"
},
"auto_restart_interval": {
"default": "60s",
"description": "The auto restart interval after the resource is disconnected.",
"oneOf": [
{
"example": "32s",
"type": "string"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"query_mode": {
"default": "async",
"description": "Query mode. Optional 'sync/async', default 'async'.",
"enum": [
"sync",
"async"
],
"type": "string"
},
"request_timeout": {
"default": "15s",
"description": "Timeout for requests. If query_mode is sync, calls to the resource will be blocked for this amount of time before timing out.",
"oneOf": [
{
"example": "32s",
"type": "string"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"async_inflight_window": {
"default": 100,
"description": "Async query inflight window.",
"minimum": 1,
"type": "integer"
},
"enable_queue": {
"default": false,
"deprecated": "since(\"v5.0.14\")",
"description": "Enable disk buffer queue (only applicable for egress bridges).
When Enabled, messages will be buffered on disk when the bridge connection is down.
When disabled the messages are buffered in RAM only.",
"type": "boolean"
},
"max_queue_bytes": {
"default": "100MB",
"description": "Maximum number of bytes to buffer for each buffer worker.",
"example": "32MB",
"type": "string"
}
},
"type": "object"
},
"emqx_gateway_api.update_coap": {
"properties": {
"heartbeat": {
"default": "30s",
"description": "The gateway server required minimum heartbeat interval.
When connection mode is enabled, this parameter is used to set the minimum heartbeat interval for the connection to be alive",
"example": "12m",
"type": "string"
},
"connection_required": {
"default": false,
"description": "Enable or disable connection mode.
Connection mode is a feature of non-standard protocols. When connection mode is enabled, it is necessary to maintain the creation, authentication and alive of connection resources",
"type": "boolean"
},
"notify_type": {
"default": "qos",
"description": "The Notification Message will be delivered to the CoAP client if a new message received on an observed topic.
The type of delivered coap message can be set to:
- non: Non-confirmable;
- con: Confirmable;
- qos: Mapping from QoS type of received message, QoS0 -> non, QoS1,2 -> con
",
"enum": [
"non",
"con",
"qos"
],
"type": "string"
},
"subscribe_qos": {
"default": "coap",
"description": "The Default QoS Level indicator for subscribe request.
This option specifies the QoS level for the CoAP Client when establishing a subscription membership, if the subscribe request is not carried `qos` option. The indicator can be set to:
- qos0, qos1, qos2: Fixed default QoS level
- coap: Dynamic QoS level by the message type of subscribe request
* qos0: If the subscribe request is non-confirmable
* qos1: If the subscribe request is confirmable
",
"enum": [
"qos0",
"qos1",
"qos2",
"coap"
],
"type": "string"
},
"publish_qos": {
"default": "coap",
"description": "The Default QoS Level indicator for publish request.
This option specifies the QoS level for the CoAP Client when publishing a message to EMQX PUB/SUB system, if the publish request is not carried `qos` option. The indicator can be set to:
- qos0, qos1, qos2: Fixed default QoS level
- coap: Dynamic QoS level by the message type of publish request
* qos0: If the publish request is non-confirmable
* qos1: If the publish request is confirmable",
"enum": [
"qos0",
"qos1",
"qos2",
"coap"
],
"type": "string"
},
"mountpoint": {
"default": "",
"description": " ",
"type": "string"
},
"enable": {
"default": true,
"description": "Whether to enable this gateway",
"type": "boolean"
},
"enable_stats": {
"default": true,
"description": "Whether to enable client process statistic",
"type": "boolean"
},
"idle_timeout": {
"default": "30s",
"description": "The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.",
"example": "12m",
"type": "string"
},
"clientinfo_override": {
"description": "ClientInfo override.",
"$ref": "#/components/schemas/gateway.clientinfo_override"
}
},
"type": "object"
},
"listeners.ssl_required_bind(with_name)": {
"required": [
"bind",
"name",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"ssl"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"name": {
"description": "Listener name",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"bind": {
"default": 8883,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
},
"ssl_options": {
"$ref": "#/components/schemas/broker.listener_ssl_opts"
}
},
"type": "object"
},
"emqx_mgmt_api_publish.publish_message": {
"required": [
"payload",
"topic"
],
"properties": {
"payload_encoding": {
"default": "plain",
"description": "MQTT Payload Encoding, base64 or plain. When set to base64, the message is decoded before it is published.",
"enum": [
"plain",
"base64"
],
"type": "string"
},
"topic": {
"description": "Topic Name",
"example": "api/example/topic",
"type": "string"
},
"qos": {
"default": 0,
"description": "MQTT message QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
},
"clientid": {
"deprecated": "since(\"v5.0.14\")",
"type": "string"
},
"payload": {
"description": "The MQTT message payload.",
"example": "hello emqx api",
"type": "string"
},
"properties": {
"description": "The Properties of the PUBLISH message.",
"$ref": "#/components/schemas/emqx_mgmt_api_publish.message_properties"
},
"retain": {
"default": false,
"description": "A boolean field to indicate if this message should be retained.",
"type": "boolean"
}
},
"type": "object"
},
"emqx_mgmt_api_clients.subscribe": {
"required": [
"topic"
],
"properties": {
"topic": {
"description": "Topic",
"type": "string"
},
"qos": {
"default": 0,
"description": "QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
},
"nl": {
"default": 0,
"description": "No Local",
"type": "integer"
},
"rap": {
"default": 0,
"description": "Retain as Published",
"type": "integer"
},
"rh": {
"default": 0,
"description": "Retain Handling",
"type": "integer"
}
},
"type": "object"
},
"emqx_authn_api.response_users": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/public.meta"
}
},
"type": "object"
},
"emqx_gateway_api.tcp_listener": {
"properties": {
"id": {
"description": "Listener ID",
"type": "string"
},
"type": {
"description": "Listener Type",
"enum": [
"tcp"
],
"type": "string"
},
"name": {
"description": "Listener Name",
"type": "string"
},
"running": {
"description": "Listener Running status",
"type": "boolean"
},
"acceptors": {
"default": 16,
"description": "Size of the acceptor pool.",
"type": "integer"
},
"tcp_options": {
"description": "Setting the TCP socket options.",
"$ref": "#/components/schemas/broker.tcp_opts"
},
"proxy_protocol": {
"default": false,
"description": "Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "15s",
"description": "Timeout for proxy protocol.
EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.",
"example": "12m",
"type": "string"
},
"enable": {
"default": true,
"description": "Enable the listener.",
"type": "boolean"
},
"bind": {
"description": "The IP address and port that the listener will bind.",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"max_connections": {
"default": 1024,
"description": "Maximum number of concurrent connections.",
"type": "integer"
},
"max_conn_rate": {
"default": 1000,
"description": "Maximum connections per second.",
"type": "integer"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"enable_authn": {
"default": true,
"description": "Set true (default) to enable client authentication on this listener.
When set to false clients will be allowed to connect without authentication.",
"type": "boolean"
},
"mountpoint": {
"description": "When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint` set to `some_tenant`, then the client actually subscribes to the topic `some_tenant/t`. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic `t`, the message is routed to all the clients subscribed `some_tenant/t`, so client A will receive the message, with topic name `t`. Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"access_rules": {
"default": "",
"description": "The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"emqx_conf_schema.log": {
"properties": {
"console_handler": {
"description": "Log handler that prints log events to the EMQX console.",
"$ref": "#/components/schemas/emqx_conf_schema.console_handler"
},
"file_handlers": {
"description": "File-based log handlers.",
"properties": {
"$name": {
"$ref": "#/components/schemas/emqx_conf_schema.log_file_handler"
}
},
"type": "object"
}
},
"type": "object"
},
"emqx_authz_api_schema.http_get": {
"required": [
"url",
"type",
"method"
],
"properties": {
"method": {
"default": "get",
"description": "HTTP method.",
"enum": [
"get"
],
"type": "string"
},
"headers": {
"default": {
"accept": "application/json",
"cache-control": "no-cache",
"connection": "keep-alive",
"keep-alive": "timeout=30, max=1000"
},
"description": "List of HTTP headers (without content-type).",
"example": {},
"type": "object"
},
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "http",
"description": "Backend type.",
"enum": [
"http"
],
"type": "string"
},
"url": {
"description": "URL of the auth server.",
"type": "string"
},
"body": {
"description": "HTTP request body.",
"example": {},
"type": "object"
},
"request_timeout": {
"default": "30s",
"description": "Request timeout.",
"type": "string"
},
"connect_timeout": {
"default": "15s",
"description": "The timeout when connecting to the HTTP server.",
"example": "32s",
"type": "string"
},
"enable_pipelining": {
"default": 100,
"description": "A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.",
"minimum": 1,
"type": "integer"
},
"max_retries": {
"deprecated": "since(\"5.0.4\")",
"minimum": 0,
"type": "integer"
},
"pool_size": {
"default": 8,
"description": "The pool size.",
"minimum": 1,
"type": "integer"
},
"request": {
"description": "Configure HTTP request parameters.",
"$ref": "#/components/schemas/connector-http.request"
},
"retry_interval": {
"deprecated": "since(\"5.0.4\")",
"example": "12m",
"type": "string"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"emqx_mgmt_api_clients.unsubscribe": {
"properties": {
"topic": {
"description": "Topic",
"type": "string"
}
},
"type": "object"
},
"emqx_mgmt_api_metrics.node_metrics": {
"properties": {
"node": {
"description": "Node name",
"type": "string"
},
"actions.failure": {
"description": "Number of failure executions of the rule engine action",
"minimum": 0,
"type": "integer"
},
"actions.success": {
"description": "Number of successful executions of the rule engine action",
"minimum": 0,
"type": "integer"
},
"bytes.received": {
"description": "Number of bytes received ",
"minimum": 0,
"type": "integer"
},
"bytes.sent": {
"description": "Number of bytes sent on this connection",
"minimum": 0,
"type": "integer"
},
"client.auth.anonymous": {
"description": "Number of clients who log in anonymously",
"minimum": 0,
"type": "integer"
},
"client.authenticate": {
"description": "Number of client authentications",
"minimum": 0,
"type": "integer"
},
"client.check_authz": {
"description": "Number of Authorization rule checks",
"minimum": 0,
"type": "integer"
},
"client.connack": {
"description": "Number of CONNACK packet sent",
"minimum": 0,
"type": "integer"
},
"client.connect": {
"description": "Number of client connections",
"minimum": 0,
"type": "integer"
},
"client.connected": {
"description": "Number of successful client connections",
"minimum": 0,
"type": "integer"
},
"client.disconnected": {
"description": "Number of client disconnects",
"minimum": 0,
"type": "integer"
},
"client.subscribe": {
"description": "Number of client subscriptions",
"minimum": 0,
"type": "integer"
},
"client.unsubscribe": {
"description": "Number of client unsubscriptions",
"minimum": 0,
"type": "integer"
},
"delivery.dropped": {
"description": "Total number of discarded messages when sending",
"minimum": 0,
"type": "integer"
},
"delivery.dropped.expired": {
"description": "Number of messages dropped due to message expiration on sending",
"minimum": 0,
"type": "integer"
},
"delivery.dropped.no_local": {
"description": "Number of messages that were dropped due to the No Local subscription option when sending",
"minimum": 0,
"type": "integer"
},
"delivery.dropped.qos0_msg": {
"description": "Number of messages with QoS 0 that were dropped because the message queue was full when sending",
"minimum": 0,
"type": "integer"
},
"delivery.dropped.queue_full": {
"description": "Number of messages with a non-zero QoS that were dropped because the message queue was full when sending",
"minimum": 0,
"type": "integer"
},
"delivery.dropped.too_large": {
"description": "The number of messages that were dropped because the length exceeded the limit when sending",
"minimum": 0,
"type": "integer"
},
"messages.acked": {
"description": "Number of received PUBACK and PUBREC packet",
"minimum": 0,
"type": "integer"
},
"messages.delayed": {
"description": "Number of delay-published messages",
"minimum": 0,
"type": "integer"
},
"messages.delivered": {
"description": "Number of messages forwarded to the subscription process internally",
"minimum": 0,
"type": "integer"
},
"messages.dropped": {
"description": "Total number of messages dropped before forwarding to the subscription process",
"minimum": 0,
"type": "integer"
},
"messages.dropped.await_pubrel_timeout": {
"description": "Number of messages dropped due to waiting PUBREL timeout",
"minimum": 0,
"type": "integer"
},
"messages.dropped.no_subscribers": {
"description": "Number of messages dropped due to no subscribers",
"minimum": 0,
"type": "integer"
},
"messages.forward": {
"description": "Number of messages forwarded to other nodes",
"minimum": 0,
"type": "integer"
},
"messages.publish": {
"description": "Number of messages published in addition to system messages",
"minimum": 0,
"type": "integer"
},
"messages.qos0.received": {
"description": "Number of QoS 0 messages received from clients",
"minimum": 0,
"type": "integer"
},
"messages.qos0.sent": {
"description": "Number of QoS 0 messages sent to clients",
"minimum": 0,
"type": "integer"
},
"messages.qos1.received": {
"description": "Number of QoS 1 messages received from clients",
"minimum": 0,
"type": "integer"
},
"messages.qos1.sent": {
"description": "Number of QoS 1 messages sent to clients",
"minimum": 0,
"type": "integer"
},
"messages.qos2.received": {
"description": "Number of QoS 2 messages received from clients",
"minimum": 0,
"type": "integer"
},
"messages.qos2.sent": {
"description": "Number of QoS 2 messages sent to clients",
"minimum": 0,
"type": "integer"
},
"messages.received": {
"description": "Number of messages received from the client, equal to the sum of messages.qos0.received\fmessages.qos1.received and messages.qos2.received",
"minimum": 0,
"type": "integer"
},
"messages.retained": {
"description": "Number of retained messages",
"minimum": 0,
"type": "integer"
},
"messages.sent": {
"description": "Number of messages sent to the client, equal to the sum of messages.qos0.sent\fmessages.qos1.sent and messages.qos2.sent",
"minimum": 0,
"type": "integer"
},
"packets.auth.received": {
"description": "Number of received AUTH packet",
"minimum": 0,
"type": "integer"
},
"packets.auth.sent": {
"description": "Number of sent AUTH packet",
"minimum": 0,
"type": "integer"
},
"packets.connack.auth_error": {
"description": "Number of received CONNECT packet with failed authentication",
"minimum": 0,
"type": "integer"
},
"packets.connack.error": {
"description": "Number of received CONNECT packet with unsuccessful connections",
"minimum": 0,
"type": "integer"
},
"packets.connack.sent": {
"description": "Number of sent CONNACK packet",
"minimum": 0,
"type": "integer"
},
"packets.connect.received": {
"description": "Number of received CONNECT packet",
"minimum": 0,
"type": "integer"
},
"packets.disconnect.received": {
"description": "Number of received DISCONNECT packet",
"minimum": 0,
"type": "integer"
},
"packets.disconnect.sent": {
"description": "Number of sent DISCONNECT packet",
"minimum": 0,
"type": "integer"
},
"packets.pingreq.received": {
"description": "Number of received PINGREQ packet",
"minimum": 0,
"type": "integer"
},
"packets.pingresp.sent": {
"description": "Number of sent PUBRESP packet",
"minimum": 0,
"type": "integer"
},
"packets.puback.inuse": {
"description": "Number of received PUBACK packet with occupied identifiers",
"minimum": 0,
"type": "integer"
},
"packets.puback.missed": {
"description": "Number of received packet with identifiers.",
"minimum": 0,
"type": "integer"
},
"packets.puback.received": {
"description": "Number of received PUBACK packet",
"minimum": 0,
"type": "integer"
},
"packets.puback.sent": {
"description": "Number of sent PUBACK packet",
"minimum": 0,
"type": "integer"
},
"packets.pubcomp.inuse": {
"description": "Number of received PUBCOMP packet with occupied identifiers",
"minimum": 0,
"type": "integer"
},
"packets.pubcomp.missed": {
"description": "Number of missed PUBCOMP packet",
"minimum": 0,
"type": "integer"
},
"packets.pubcomp.received": {
"description": "Number of received PUBCOMP packet",
"minimum": 0,
"type": "integer"
},
"packets.pubcomp.sent": {
"description": "Number of sent PUBCOMP packet",
"minimum": 0,
"type": "integer"
},
"packets.publish.auth_error": {
"description": "Number of received PUBLISH packets with failed the Authorization check",
"minimum": 0,
"type": "integer"
},
"packets.publish.dropped": {
"description": "Number of messages discarded due to the receiving limit",
"minimum": 0,
"type": "integer"
},
"packets.publish.error": {
"description": "Number of received PUBLISH packet that cannot be published",
"minimum": 0,
"type": "integer"
},
"packets.publish.inuse": {
"description": "Number of received PUBLISH packet with occupied identifiers",
"minimum": 0,
"type": "integer"
},
"packets.publish.received": {
"description": "Number of received PUBLISH packet",
"minimum": 0,
"type": "integer"
},
"packets.publish.sent": {
"description": "Number of sent PUBLISH packet",
"minimum": 0,
"type": "integer"
},
"packets.pubrec.inuse": {
"description": "Number of received PUBREC packet with occupied identifiers",
"minimum": 0,
"type": "integer"
},
"packets.pubrec.missed": {
"description": "Number of received PUBREC packet with unknown identifiers",
"minimum": 0,
"type": "integer"
},
"packets.pubrec.received": {
"description": "Number of received PUBREC packet",
"minimum": 0,
"type": "integer"
},
"packets.pubrec.sent": {
"description": "Number of sent PUBREC packet",
"minimum": 0,
"type": "integer"
},
"packets.pubrel.missed": {
"description": "Number of received PUBREC packet with unknown identifiers",
"minimum": 0,
"type": "integer"
},
"packets.pubrel.received": {
"description": "Number of received PUBREL packet",
"minimum": 0,
"type": "integer"
},
"packets.pubrel.sent": {
"description": "Number of sent PUBREL packet",
"minimum": 0,
"type": "integer"
},
"packets.received": {
"description": "Number of received packet",
"minimum": 0,
"type": "integer"
},
"packets.sent": {
"description": "Number of sent packet",
"minimum": 0,
"type": "integer"
},
"packets.suback.sent": {
"description": "Number of sent SUBACK packet",
"minimum": 0,
"type": "integer"
},
"packets.subscribe.auth_error": {
"description": "Number of received SUBACK packet with failed Authorization check",
"minimum": 0,
"type": "integer"
},
"packets.subscribe.error": {
"description": "Number of received SUBSCRIBE packet with failed subscriptions",
"minimum": 0,
"type": "integer"
},
"packets.subscribe.received": {
"description": "Number of received SUBSCRIBE packet",
"minimum": 0,
"type": "integer"
},
"packets.unsuback.sent": {
"description": "Number of sent UNSUBACK packet",
"minimum": 0,
"type": "integer"
},
"packets.unsubscribe.error": {
"description": "Number of received UNSUBSCRIBE packet with failed unsubscriptions",
"minimum": 0,
"type": "integer"
},
"packets.unsubscribe.received": {
"description": "Number of received UNSUBSCRIBE packet",
"minimum": 0,
"type": "integer"
},
"rules.matched": {
"description": "Number of rule matched",
"minimum": 0,
"type": "integer"
},
"session.created": {
"description": "Number of sessions created",
"minimum": 0,
"type": "integer"
},
"session.discarded": {
"description": "Number of sessions dropped because Clean Session or Clean Start is true",
"minimum": 0,
"type": "integer"
},
"session.resumed": {
"description": "Number of sessions resumed because Clean Session or Clean Start is false",
"minimum": 0,
"type": "integer"
},
"session.takenover": {
"description": "Number of sessions takenover because Clean Session or Clean Start is false",
"minimum": 0,
"type": "integer"
},
"session.terminated": {
"description": "Number of terminated sessions",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"listeners.ws_required_bind(with_name)": {
"required": [
"bind",
"name",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"ws"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"name": {
"description": "Listener name",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"bind": {
"default": 8083,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
},
"websocket": {
"$ref": "#/components/schemas/broker.ws_opts"
}
},
"type": "object"
},
"listeners.quic_not_required_bind": {
"required": [
"id",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"quic"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"id": {
"description": "Listener id",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"bind": {
"default": 14567,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"certfile": {
"description": "Path to the certificate file.",
"type": "string"
},
"keyfile": {
"description": "Path to the secret key file. ",
"type": "string"
},
"ciphers": {
"default": [
"TLS_AES_256_GCM_SHA384",
"TLS_AES_128_GCM_SHA256",
"TLS_CHACHA20_POLY1305_SHA256"
],
"description": "
This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\" or
[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"].
Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.
The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.
NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
PSK cipher suites: \"RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA\"
NOTE: QUIC listener supports only 'tlsv1.3' ciphers
",
"items": {
"type": "string"
},
"type": "array"
},
"idle_timeout": {
"default": 0,
"description": "How long a connection can go idle before it is gracefully shut down. 0 to disable",
"example": "32s",
"type": "string"
},
"handshake_idle_timeout": {
"default": "10s",
"description": "How long a handshake can idle before it is discarded. ",
"example": "32s",
"type": "string"
},
"keep_alive_interval": {
"default": 0,
"description": "
How often to send PING frames to keep a connection alive. 0 means disabled.
",
"example": "32s",
"type": "string"
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
}
},
"type": "object"
},
"retainer.message": {
"properties": {
"payload": {
"description": "Payload.",
"type": "string"
},
"msgid": {
"description": "Message ID.",
"type": "string"
},
"topic": {
"description": "Topic.",
"type": "string"
},
"qos": {
"description": "QoS.",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
},
"publish_at": {
"description": "Message publish time, RFC 3339 format.",
"type": "string"
},
"from_clientid": {
"description": "The clientid of publisher.",
"type": "string"
},
"from_username": {
"description": "The username of publisher.",
"type": "string"
}
},
"type": "object"
},
"emqx_authn_schema.node_status": {
"properties": {
"node": {
"description": "Node name.",
"example": "emqx@127.0.0.1",
"type": "string"
},
"status": {
"description": "The status of the resource for each node.",
"enum": [
"connected",
"disconnected",
"connecting"
],
"type": "string"
}
},
"type": "object"
},
"exhook.server_config": {
"required": [
"url",
"name"
],
"properties": {
"name": {
"description": "Name of the exhook server",
"example": "default",
"type": "string"
},
"enable": {
"default": true,
"description": "Enable this Exhook server",
"type": "boolean"
},
"url": {
"description": "URL of the gRPC server",
"example": "http://127.0.0.1:9000",
"type": "string"
},
"request_timeout": {
"default": "5s",
"description": "The timeout of request gRPC server",
"example": "12m",
"type": "string"
},
"failed_action": {
"default": "deny",
"description": "The value that is returned when the request to the gRPC server fails for any reason",
"enum": [
"deny",
"ignore"
],
"type": "string"
},
"ssl": {
"$ref": "#/components/schemas/exhook.ssl_conf"
},
"socket_options": {
"default": {
"keepalive": true,
"nodelay": true
},
"$ref": "#/components/schemas/exhook.socket_options"
},
"auto_reconnect": {
"default": "60s",
"description": "Whether to automatically reconnect (initialize) the gRPC server.
When gRPC is not available, Exhook tries to request the gRPC service at that interval and reinitialize the list of mounted hooks.",
"oneOf": [
{
"example": "12m",
"type": "string"
},
{
"enum": [
false
],
"type": "string"
}
]
},
"pool_size": {
"default": 8,
"description": "The process pool size for gRPC client",
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"emqx_rule_api_schema.ctx_sub": {
"required": [
"event_type"
],
"properties": {
"event_type": {
"description": "Event Type",
"enum": [
"session_subscribed"
],
"type": "string"
},
"clientid": {
"description": "The Client ID",
"type": "string"
},
"username": {
"description": "The User Name",
"type": "string"
},
"payload": {
"description": "The Message Payload",
"type": "string"
},
"peerhost": {
"description": "The IP Address of the Peer Client",
"type": "string"
},
"topic": {
"description": "Message Topic",
"type": "string"
},
"publish_received_at": {
"description": "The Time that this Message is Received",
"type": "integer"
},
"qos": {
"description": "The Message QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"emqx_conf_schema.cluster_k8s": {
"properties": {
"apiserver": {
"default": "http://10.110.111.204:8080",
"description": "Kubernetes API endpoint URL.",
"readOnly": true,
"type": "string"
},
"service_name": {
"default": "emqx",
"description": "EMQX broker service name.",
"readOnly": true,
"type": "string"
},
"address_type": {
"default": "ip",
"description": "Address type used for connecting to the discovered nodes.
Setting cluster.k8s.address_type to ip will
make EMQX to discover IP addresses of peer nodes from Kubernetes API.
",
"enum": [
"ip",
"dns",
"hostname"
],
"readOnly": true,
"type": "string"
},
"namespace": {
"default": "default",
"description": "Kubernetes namespace.",
"readOnly": true,
"type": "string"
},
"suffix": {
"default": "pod.local",
"description": "Node name suffix.
Note: this parameter is only relevant when address_type is dns
or hostname.",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"gateway.clientinfo_override": {
"properties": {
"username": {
"description": "Template for overriding username.",
"type": "string"
},
"password": {
"description": "Template for overriding password.",
"format": "password",
"type": "string"
},
"clientid": {
"description": "Template for overriding clientid.",
"type": "string"
}
},
"type": "object"
},
"statsd.statsd": {
"properties": {
"enable": {
"default": false,
"description": "Enable or disable StatsD metrics collection and push service.",
"type": "boolean"
},
"server": {
"default": "127.0.0.1:8125",
"description": "StatsD server address.",
"type": "string"
},
"sample_time_interval": {
"default": "30s",
"description": "The sampling interval for metrics.",
"example": "32s",
"type": "string"
},
"flush_time_interval": {
"default": "30s",
"description": "The push interval for metrics.",
"example": "32s",
"type": "string"
},
"tags": {
"default": {},
"description": "The tags for metrics.",
"example": {},
"type": "object"
}
},
"type": "object"
},
"emqx_rule_api_schema.rule_events": {
"required": [
"event"
],
"properties": {
"event": {
"description": "The event topics",
"enum": [
"$events/client_connected",
"$events/client_disconnected",
"$events/client_connack",
"$events/client_check_authz_complete",
"$events/session_subscribed",
"$events/session_unsubscribed",
"$events/message_delivered",
"$events/message_acked",
"$events/message_dropped",
"$events/delivery_dropped"
],
"type": "string"
},
"title": {
"description": "The title",
"example": "some title",
"type": "string"
},
"description": {
"description": "The description",
"example": "some desc",
"type": "string"
},
"columns": {
"description": "The columns",
"example": {},
"type": "object"
},
"test_columns": {
"description": "The test columns",
"example": {},
"type": "object"
},
"sql_example": {
"description": "The sql_example",
"type": "string"
}
},
"type": "object"
},
"exhook.socket_options": {
"properties": {
"keepalive": {
"default": true,
"description": "Enables/disables periodic transmission on a connected socket when no other data is exchanged.
If the other end does not respond, the connection is considered broken and an error message is sent to the controlling process.",
"type": "boolean"
},
"nodelay": {
"default": true,
"description": "If true, option TCP_NODELAY is turned on for the socket,
which means that also small amounts of data are sent immediately",
"type": "boolean"
},
"recbuf": {
"description": "The minimum size of receive buffer to use for the socket",
"example": "64KB",
"type": "string"
},
"sndbuf": {
"description": "The minimum size of send buffer to use for the socket",
"example": "16KB",
"type": "string"
}
},
"type": "object"
},
"emqx_mgmt_api_clients.keepalive": {
"properties": {
"interval": {
"description": "Keepalive time, with the unit of second",
"type": "integer"
}
},
"type": "object"
},
"listeners.status": {
"required": [
"running"
],
"properties": {
"running": {
"description": "Listener running status",
"oneOf": [
{
"type": "boolean"
},
{
"enum": [
"inconsistent"
],
"type": "string"
}
]
},
"max_connections": {
"description": "Max connections",
"oneOf": [
{
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"listeners.ws_not_required_bind": {
"required": [
"id",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"ws"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"id": {
"description": "Listener id",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"bind": {
"default": 8083,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
},
"websocket": {
"$ref": "#/components/schemas/broker.ws_opts"
}
},
"type": "object"
},
"connector-mqtt.egress": {
"required": [
"remote"
],
"properties": {
"local": {
"description": "The configs about receiving messages from local broker.",
"$ref": "#/components/schemas/connector-mqtt.egress_local"
},
"remote": {
"description": "The configs about sending message to the remote broker.",
"$ref": "#/components/schemas/connector-mqtt.egress_remote"
}
},
"type": "object"
},
"emqx_authn_api.request_user_update": {
"required": [
"password"
],
"properties": {
"password": {
"type": "string"
},
"is_superuser": {
"default": false,
"type": "boolean"
}
},
"type": "object"
},
"emqx_gateway_api_clients.subscription": {
"properties": {
"topic": {
"description": "Topic Filter/Name",
"type": "string"
},
"qos": {
"description": "QoS level, enum: 0, 1, 2",
"type": "integer"
},
"nl": {
"description": "No Local option, enum: 0, 1",
"type": "integer"
},
"rap": {
"description": "Retain as Published option, enum: 0, 1",
"type": "integer"
},
"rh": {
"description": "Retain Handling option, enum: 0, 1, 2",
"type": "integer"
},
"sub_props": {
"description": "Subscription properties",
"$ref": "#/components/schemas/emqx_gateway_api_clients.extra_sub_props"
}
},
"type": "object"
},
"emqx_gateway_api.ssl_listener": {
"properties": {
"id": {
"description": "Listener ID",
"type": "string"
},
"type": {
"description": "Listener Type",
"enum": [
"ssl"
],
"type": "string"
},
"name": {
"description": "Listener Name",
"type": "string"
},
"running": {
"description": "Listener Running status",
"type": "boolean"
},
"acceptors": {
"default": 16,
"description": "Size of the acceptor pool.",
"type": "integer"
},
"tcp_options": {
"description": "Setting the TCP socket options.",
"$ref": "#/components/schemas/broker.tcp_opts"
},
"proxy_protocol": {
"default": false,
"description": "Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "15s",
"description": "Timeout for proxy protocol.
EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.",
"example": "12m",
"type": "string"
},
"enable": {
"default": true,
"description": "Enable the listener.",
"type": "boolean"
},
"bind": {
"description": "The IP address and port that the listener will bind.",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"max_connections": {
"default": 1024,
"description": "Maximum number of concurrent connections.",
"type": "integer"
},
"max_conn_rate": {
"default": 1000,
"description": "Maximum connections per second.",
"type": "integer"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"enable_authn": {
"default": true,
"description": "Set true (default) to enable client authentication on this listener.
When set to false clients will be allowed to connect without authentication.",
"type": "boolean"
},
"mountpoint": {
"description": "When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint` set to `some_tenant`, then the client actually subscribes to the topic `some_tenant/t`. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic `t`, the message is routed to all the clients subscribed `some_tenant/t`, so client A will receive the message, with topic name `t`. Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"access_rules": {
"default": "",
"description": "The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny",
"items": {
"type": "string"
},
"type": "array"
},
"ssl_options": {
"description": "SSL Socket options.",
"$ref": "#/components/schemas/broker.listener_ssl_opts"
}
},
"type": "object"
},
"emqx_authz_api_schema.http_post": {
"required": [
"url",
"type",
"method"
],
"properties": {
"method": {
"default": "post",
"description": "HTTP method.",
"enum": [
"post"
],
"type": "string"
},
"headers": {
"default": {
"accept": "application/json",
"cache-control": "no-cache",
"connection": "keep-alive",
"content-type": "application/json",
"keep-alive": "timeout=30, max=1000"
},
"description": "List of HTTP Headers.",
"example": {},
"type": "object"
},
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "http",
"description": "Backend type.",
"enum": [
"http"
],
"type": "string"
},
"url": {
"description": "URL of the auth server.",
"type": "string"
},
"body": {
"description": "HTTP request body.",
"example": {},
"type": "object"
},
"request_timeout": {
"default": "30s",
"description": "Request timeout.",
"type": "string"
},
"connect_timeout": {
"default": "15s",
"description": "The timeout when connecting to the HTTP server.",
"example": "32s",
"type": "string"
},
"enable_pipelining": {
"default": 100,
"description": "A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.",
"minimum": 1,
"type": "integer"
},
"max_retries": {
"deprecated": "since(\"5.0.4\")",
"minimum": 0,
"type": "integer"
},
"pool_size": {
"default": 8,
"description": "The pool size.",
"minimum": 1,
"type": "integer"
},
"request": {
"description": "Configure HTTP request parameters.",
"$ref": "#/components/schemas/connector-http.request"
},
"retry_interval": {
"deprecated": "since(\"5.0.4\")",
"example": "12m",
"type": "string"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"retainer.mnesia_config": {
"properties": {
"type": {
"default": "built_in_database",
"description": "Backend type.",
"enum": [
"built_in_database"
],
"type": "string"
},
"storage_type": {
"default": "ram",
"description": "Specifies whether the messages are stored in RAM or persisted on disc.",
"enum": [
"ram",
"disc"
],
"type": "string"
},
"max_retained_messages": {
"default": 0,
"description": "Maximum number of retained messages. 0 means no limit.",
"minimum": 0,
"type": "integer"
},
"index_specs": {
"default": [
[
1,
2,
3
],
[
1,
3
],
[
2,
3
],
[
3
]
],
"description": "Retainer index specifications: list of arrays of positive ascending integers. Each array specifies an index. Numbers in an index specification are 1-based word positions in topics. Words from specified positions will be used for indexing.
For example, it is good to have [2, 4] index to optimize +/X/+/Y/... topic wildcard subscriptions.",
"example": [
[
2,
4
],
[
1,
3
]
],
"items": {
"type": "integer"
},
"type": "array"
}
},
"type": "object"
},
"emqx_conf_schema.console_handler": {
"properties": {
"enable": {
"default": false,
"description": "Enable this log handler.",
"type": "boolean"
},
"level": {
"default": "warning",
"description": "
The log level for the current log handler.
Defaults to warning.
",
"enum": [
"debug",
"info",
"notice",
"warning",
"error",
"critical",
"alert",
"emergency",
"all"
],
"type": "string"
},
"time_offset": {
"default": "system",
"description": "
The time offset to be used when formatting the timestamp.
Can be one of:
- system: the time offset used by the local system
- utc: the UTC time offset
- +-[hh]:[mm]: user specified time offset, such as \"-02:00\" or \"+00:00\"
Defaults to: system.
",
"type": "string"
},
"chars_limit": {
"default": "unlimited",
"description": "
Set the maximum length of a single log message. If this length is exceeded, the log message will be truncated.
NOTE: Restrict char limiter if formatter is JSON , it will get a truncated incomplete JSON data, which is not recommended.
",
"oneOf": [
{
"minimum": 100,
"type": "integer"
},
{
"enum": [
"unlimited"
],
"type": "string"
}
]
},
"formatter": {
"default": "text",
"description": "Choose log formatter. text for free text, and json for structured logging.",
"enum": [
"text",
"json"
],
"type": "string"
},
"single_line": {
"default": true,
"description": "Print logs in a single line if set to true. Otherwise, log messages may span multiple lines.",
"type": "boolean"
},
"sync_mode_qlen": {
"default": 100,
"description": "As long as the number of buffered log events is lower than this value,
all log events are handled asynchronously. This means that the client process sending the log event,
by calling a log function in the Logger API, does not wait for a response from the handler
but continues executing immediately after the event is sent.
It is not affected by the time it takes the handler to print the event to the log device.
If the message queue grows larger than this value,
the handler starts handling log events synchronously instead,
meaning that the client process sending the event must wait for a response.
When the handler reduces the message queue to a level below the sync_mode_qlen threshold,
asynchronous operation is resumed.
",
"minimum": 0,
"type": "integer"
},
"drop_mode_qlen": {
"default": 3000,
"description": "When the number of buffered log events is larger than this value, the new log events are dropped.
When drop mode is activated or deactivated, a message is printed in the logs.",
"minimum": 1,
"type": "integer"
},
"flush_qlen": {
"default": 8000,
"description": "If the number of buffered log events grows larger than this threshold, a flush (delete) operation takes place.
To flush events, the handler discards the buffered log messages without logging.",
"minimum": 1,
"type": "integer"
},
"overload_kill": {
"$ref": "#/components/schemas/emqx_conf_schema.log_overload_kill"
},
"burst_limit": {
"$ref": "#/components/schemas/emqx_conf_schema.log_burst_limit"
},
"supervisor_reports": {
"default": "error",
"description": "
Type of supervisor reports that are logged. Defaults to error
- error: only log errors in the Erlang processes.
- progress: log process startup.
",
"enum": [
"error",
"progress"
],
"type": "string"
},
"max_depth": {
"default": 100,
"description": "Maximum depth for Erlang term log formatting and Erlang process message queue inspection.",
"oneOf": [
{
"minimum": 0,
"type": "integer"
},
{
"enum": [
"unlimited"
],
"type": "string"
}
]
}
},
"type": "object"
},
"bridge_webhook.get": {
"required": [
"url",
"name",
"type"
],
"properties": {
"status": {
"description": "The status of the bridge",
"enum": [
"connected",
"disconnected",
"connecting"
],
"type": "string"
},
"node_status": {
"description": "Node status.",
"items": {
"$ref": "#/components/schemas/bridge.node_status"
},
"type": "array"
},
"type": {
"description": "The Bridge Type",
"enum": [
"webhook"
],
"type": "string"
},
"name": {
"description": "Bridge name, used as a human-readable description of the bridge.",
"type": "string"
},
"enable": {
"default": true,
"description": "Enable or disable this bridge",
"type": "boolean"
},
"resource_opts": {
"default": {},
"description": "Resource options.",
"$ref": "#/components/schemas/bridge_webhook.creation_opts"
},
"connect_timeout": {
"default": "15s",
"description": "The timeout when connecting to the HTTP server.",
"example": "32s",
"type": "string"
},
"retry_interval": {
"deprecated": "since(\"5.0.4\")",
"example": "12m",
"type": "string"
},
"pool_type": {
"default": "random",
"description": "The type of the pool. Can be one of `random`, `hash`.",
"enum": [
"random",
"hash"
],
"type": "string"
},
"pool_size": {
"default": 8,
"description": "The pool size.",
"minimum": 1,
"type": "integer"
},
"enable_pipelining": {
"default": 100,
"description": "A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.",
"minimum": 1,
"type": "integer"
},
"request": {
"description": "Configure HTTP request parameters.",
"$ref": "#/components/schemas/connector-http.request"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
},
"url": {
"description": "
The URL of the HTTP Bridge.
Template with variables is allowed in the path, but variables cannot be used in the scheme, host,
or port part.
For example, http://localhost:9901/${topic} is allowed, but
http://${host}:9901/message or http://localhost:${port}/message
is not allowed.
",
"type": "string"
},
"direction": {
"deprecated": "since(\"5.0.12\")",
"description": "Deprecated, The direction of this bridge, MUST be 'egress'",
"enum": [
"egress"
],
"type": "string"
},
"local_topic": {
"description": "
The MQTT topic filter to be forwarded to the HTTP server. All MQTT 'PUBLISH' messages with the topic
matching the local_topic will be forwarded.
NOTE: if this bridge is used as the action of a rule (EMQX rule engine), and also local_topic is
configured, then both the data got from the rule and the MQTT messages that match local_topic
will be forwarded.
",
"type": "string"
},
"method": {
"default": "post",
"description": "
The method of the HTTP request. All the available methods are: post, put, get, delete.
Template with variables is allowed.
",
"enum": [
"post",
"put",
"get",
"delete"
],
"type": "string"
},
"headers": {
"default": {
"accept": "application/json",
"cache-control": "no-cache",
"connection": "keep-alive",
"content-type": "application/json",
"keep-alive": "timeout=5"
},
"description": "
The headers of the HTTP request.
Template with variables is allowed.
",
"example": {},
"type": "object"
},
"body": {
"description": "
The body of the HTTP request.
If not provided, the body will be a JSON object of all the available fields.
There, 'all the available fields' means the context of a MQTT message when
this webhook is triggered by receiving a MQTT message (the `local_topic` is set),
or the context of the event when this webhook is triggered by a rule (i.e. this
webhook is used as an action of a rule).
Template with variables is allowed.
",
"type": "string"
},
"max_retries": {
"default": 2,
"description": "HTTP request max retry times if failed.",
"minimum": 0,
"type": "integer"
},
"request_timeout": {
"default": "15s",
"description": "HTTP request timeout.",
"example": "32s",
"type": "string"
}
},
"type": "object"
},
"emqx_authn_schema.metrics_status_fields": {
"properties": {
"resource_metrics": {
"description": "The metrics of the resource.",
"$ref": "#/components/schemas/emqx_authn_schema.resource_metrics"
},
"node_resource_metrics": {
"description": "The metrics of the resource for each node.",
"$ref": "#/components/schemas/emqx_authn_schema.node_resource_metrics"
},
"metrics": {
"description": "The metrics of the resource.",
"$ref": "#/components/schemas/emqx_authn_schema.metrics"
},
"node_metrics": {
"description": "The metrics of the resource for each node.",
"$ref": "#/components/schemas/emqx_authn_schema.node_metrics"
},
"status": {
"description": "The status of the resource.",
"enum": [
"connected",
"disconnected",
"connecting",
"inconsistent"
],
"type": "string"
},
"node_status": {
"description": "The status of the resource for each node.",
"$ref": "#/components/schemas/emqx_authn_schema.node_status"
},
"node_error": {
"description": "The error of node.",
"$ref": "#/components/schemas/emqx_authn_schema.node_error"
}
},
"type": "object"
},
"listeners.tcp_not_required_bind": {
"required": [
"id",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"tcp"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"id": {
"description": "Listener id",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"bind": {
"default": 1883,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
}
},
"type": "object"
},
"limiter.internal": {
"properties": {
"rate": {
"default": "infinity",
"description": "Rate for this bucket.",
"example": "10MB",
"type": "string"
},
"capacity": {
"default": "infinity",
"description": "The capacity of this token bucket.",
"example": "100MB",
"type": "string"
},
"initial": {
"default": "0",
"description": "The initial number of tokens for this bucket.",
"example": "0MB",
"type": "string"
},
"client": {
"description": "The rate limit for each user of the bucket",
"$ref": "#/components/schemas/limiter.client_opts"
}
},
"type": "object"
},
"public.meta": {
"required": [
"hasnext"
],
"properties": {
"page": {
"default": 1,
"description": "Page number of the results to fetch.",
"example": 1,
"minimum": 1,
"type": "integer"
},
"limit": {
"default": 100,
"description": "Results per page(max 1000)",
"example": 50,
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"count": {
"description": "Total number of records matching the query.
Note: this field is present only if the query can be optimized and does not require a full table scan.",
"minimum": 0,
"type": "integer"
},
"hasnext": {
"description": "Flag indicating whether there are more results available on next pages.",
"type": "boolean"
}
},
"type": "object"
},
"broker.sysmon_top": {
"properties": {
"num_items": {
"default": 10,
"description": "The number of top processes per monitoring group",
"minimum": 0,
"type": "integer"
},
"sample_interval": {
"default": "2s",
"description": "Specifies how often process top should be collected",
"example": "12m",
"type": "string"
},
"max_procs": {
"default": 1000000,
"description": "Stop collecting data when the number of processes
in the VM exceeds this value",
"minimum": 0,
"type": "integer"
},
"db_hostname": {
"default": "",
"description": "Hostname of the PostgreSQL database that collects the data points",
"type": "string"
},
"db_port": {
"default": 5432,
"description": "Port of the PostgreSQL database that collects the data points.",
"type": "integer"
},
"db_username": {
"default": "system_monitor",
"description": "Username of the PostgreSQL database",
"type": "string"
},
"db_password": {
"default": "system_monitor_password",
"description": "EMQX user password in the PostgreSQL database",
"type": "string"
},
"db_name": {
"default": "postgres",
"description": "PostgreSQL database name",
"type": "string"
}
},
"type": "object"
},
"emqx_gateway_api_clients.extra_sub_props": {
"properties": {
"subid": {
"description": "Only stomp protocol, a unique identity for the subscription. range: 1-65535.",
"type": "string"
}
},
"type": "object"
},
"emqx_telemetry_api.status": {
"properties": {
"enable": {
"default": true,
"description": "Enable telemetry",
"example": false,
"type": "boolean"
}
},
"type": "object"
},
"authn-hash.bcrypt_rw": {
"required": [
"name"
],
"properties": {
"name": {
"description": "BCRYPT password hashing.",
"enum": [
"bcrypt"
],
"type": "string"
},
"salt_rounds": {
"default": 10,
"description": "Salt rounds for BCRYPT password generation.",
"example": 10,
"type": "integer"
}
},
"type": "object"
},
"broker.event_names": {
"properties": {
"client_connected": {
"default": true,
"description": "Enable to publish client connected event messages",
"type": "boolean"
},
"client_disconnected": {
"default": true,
"description": "Enable to publish client disconnected event messages.",
"type": "boolean"
},
"client_subscribed": {
"default": false,
"description": "Enable to publish event message that client subscribed a topic successfully.",
"type": "boolean"
},
"client_unsubscribed": {
"default": false,
"description": "Enable to publish event message that client unsubscribed a topic successfully.",
"type": "boolean"
}
},
"type": "object"
},
"gateway.dtls_opts": {
"properties": {
"cacertfile": {
"description": "
Trusted PEM format CA certificates bundle file.
The certificates in this file are used to verify the TLS peer's certificates.
Append new certificates to the file if new CAs are to be trusted.
There is no need to restart EMQX to have the updated file loaded, because
the system regularly checks if file has been updated (and reload).
NOTE: invalidating (deleting) a certificate from the file will not affect
already established connections.
",
"type": "string"
},
"certfile": {
"description": "
PEM format certificates chain file.
The certificates in this file should be in reversed order of the certificate
issue chain. That is, the host's certificate should be placed in the beginning
of the file, followed by the immediate issuer certificate and so on.
Although the root CA certificate is optional, it should be placed at the end of
the file if it is to be added.
",
"type": "string"
},
"keyfile": {
"description": "PEM format private key file. ",
"type": "string"
},
"verify": {
"default": "verify_none",
"description": "Enable or disable peer verification. ",
"enum": [
"verify_peer",
"verify_none"
],
"type": "string"
},
"reuse_sessions": {
"default": true,
"description": "Enable TLS session reuse. ",
"type": "boolean"
},
"depth": {
"default": 10,
"description": "
Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path.
So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly;
if 1 the path can be PEER, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
",
"type": "integer"
},
"password": {
"description": "
String containing the user's password.
Only used if the private key file is password-protected.
",
"example": "",
"format": "password",
"type": "string"
},
"versions": {
"default": [
"dtlsv1.2",
"dtlsv1"
],
"description": "
All TLS/DTLS versions to be supported.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
In case PSK cipher suites are intended, make sure to configure
['tlsv1.2', 'tlsv1.1'] here.
",
"items": {
"type": "string"
},
"type": "array"
},
"ciphers": {
"default": "",
"description": "
This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\" or
[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"].
Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.
The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.
NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
PSK cipher suites: \"RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA\"
",
"items": {
"type": "string"
},
"type": "array"
},
"user_lookup_fun": {
"default": "emqx_tls_psk:lookup",
"description": "EMQX-internal callback that is used to lookup pre-shared key (PSK) identity. ",
"type": "string"
},
"secure_renegotiate": {
"default": true,
"description": "
SSL parameter renegotiation is a feature that allows a client and a server
to renegotiate the parameters of the SSL connection on the fly.
RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation,
you drop support for the insecure renegotiation, prone to MitM attacks.
",
"type": "boolean"
},
"dhfile": {
"description": "
Path to a file containing PEM-encoded Diffie-Hellman parameters
to be used by the server if a cipher suite using Diffie-Hellman
key exchange is negotiated. If not specified, default parameters
are used.
NOTE: The dhfile option is not supported by TLS 1.3.
",
"type": "string"
},
"fail_if_no_peer_cert": {
"default": false,
"description": "
Used together with {verify, verify_peer} by an TLS/DTLS server.
If set to true, the server fails if the client does not have a
certificate to send, that is, sends an empty certificate.
If set to false, it fails only if the client sends an invalid
certificate (an empty certificate is considered valid).
",
"type": "boolean"
},
"honor_cipher_order": {
"default": true,
"description": "
An important security setting, it forces the cipher to be set based
on the server-specified order instead of the client-specified order,
hence enforcing the (usually more properly configured) security
ordering of the server administrator.
",
"type": "boolean"
},
"client_renegotiation": {
"default": true,
"description": "
In protocols that support client-initiated renegotiation,
the cost of resources of such an operation is higher for the server than the client.
This can act as a vector for denial of service attacks.
The SSL application already takes measures to counter-act such attempts,
but client-initiated renegotiation can be strictly disabled by setting this option to false.
The default value is true. Note that disabling renegotiation can result in
long-lived connections becoming unusable due to limits on
the number of messages the underlying cipher suite can encipher.
",
"type": "boolean"
},
"handshake_timeout": {
"default": "15s",
"description": "
Maximum time duration allowed for the handshake to complete
",
"example": "12m",
"type": "string"
},
"gc_after_handshake": {
"default": false,
"description": "
Memory usage tuning. If enabled, will immediately perform a garbage collection after
the TLS/SSL handshake.
",
"type": "boolean"
}
},
"type": "object"
},
"authn-http.post": {
"required": [
"url",
"backend",
"mechanism",
"method"
],
"properties": {
"method": {
"default": "post",
"description": "HTTP request method.",
"enum": [
"post"
],
"type": "string"
},
"headers": {
"default": {
"accept": "application/json",
"cache-control": "no-cache",
"connection": "keep-alive",
"content-type": "application/json",
"keep-alive": "timeout=30, max=1000"
},
"description": "List of HTTP Headers.",
"example": {},
"type": "object"
},
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"password_based"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"http"
],
"type": "string"
},
"url": {
"description": "URL of the HTTP server.",
"type": "string"
},
"body": {
"description": "HTTP request body.",
"example": {},
"type": "object"
},
"request_timeout": {
"default": "5s",
"description": "HTTP request timeout.",
"example": "32s",
"type": "string"
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
},
"connect_timeout": {
"default": "15s",
"description": "The timeout when connecting to the HTTP server.",
"example": "32s",
"type": "string"
},
"enable_pipelining": {
"default": 100,
"description": "A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.",
"minimum": 1,
"type": "integer"
},
"max_retries": {
"deprecated": "since(\"5.0.4\")",
"minimum": 0,
"type": "integer"
},
"pool_size": {
"default": 8,
"description": "The pool size.",
"minimum": 1,
"type": "integer"
},
"request": {
"description": "Configure HTTP request parameters.",
"$ref": "#/components/schemas/connector-http.request"
},
"retry_interval": {
"deprecated": "since(\"5.0.4\")",
"example": "12m",
"type": "string"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"emqx_gateway_api_clients.stomp_client": {
"properties": {
"node": {
"description": "Name of the node to which the client is connected",
"type": "string"
},
"clientid": {
"description": "Client ID",
"type": "string"
},
"username": {
"description": "Username of client when connecting",
"type": "string"
},
"mountpoint": {
"description": "Topic mountpoint",
"type": "string"
},
"proto_name": {
"description": "Client protocol name",
"type": "string"
},
"proto_ver": {
"description": "Protocol version used by the client",
"type": "string"
},
"ip_address": {
"description": "Client's IP address",
"type": "string"
},
"port": {
"description": "Client's port",
"type": "integer"
},
"is_bridge": {
"description": "Indicates whether the client is connected via bridge",
"type": "boolean"
},
"connected_at": {
"description": "Client connection time",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"disconnected_at": {
"description": "Client offline time, This field is only valid and returned when connected is false",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"connected": {
"description": "Whether the client is connected",
"type": "boolean"
},
"keepalive": {
"description": "Keepalive time, with the unit of second",
"type": "integer"
},
"clean_start": {
"description": "Indicate whether the client is using a brand new session",
"type": "boolean"
},
"expiry_interval": {
"description": "Session expiration interval, with the unit of second",
"type": "integer"
},
"created_at": {
"description": "Session creation time",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"subscriptions_cnt": {
"description": "Number of subscriptions established by this client",
"type": "integer"
},
"subscriptions_max": {
"description": "Maximum number of subscriptions allowed by this client",
"type": "integer"
},
"inflight_cnt": {
"description": "Current length of inflight",
"type": "integer"
},
"inflight_max": {
"description": "Maximum length of inflight",
"type": "integer"
},
"mqueue_len": {
"description": "Current length of message queue",
"type": "integer"
},
"mqueue_max": {
"description": "Maximum length of message queue",
"type": "integer"
},
"mqueue_dropped": {
"description": "Number of messages dropped by the message queue due to exceeding the length",
"type": "integer"
},
"awaiting_rel_cnt": {
"description": "Number of awaiting acknowledge packet",
"type": "integer"
},
"awaiting_rel_max": {
"description": "Maximum allowed number of awaiting PUBREC packet",
"type": "integer"
},
"recv_oct": {
"description": "Number of bytes received",
"type": "integer"
},
"recv_cnt": {
"description": "Number of socket packets received",
"type": "integer"
},
"recv_pkt": {
"description": "Number of protocol packets received",
"type": "integer"
},
"recv_msg": {
"description": "Number of message packets received",
"type": "integer"
},
"send_oct": {
"description": "Number of bytes sent",
"type": "integer"
},
"send_cnt": {
"description": "Number of socket packets sent",
"type": "integer"
},
"send_pkt": {
"description": "Number of protocol packets sent",
"type": "integer"
},
"send_msg": {
"description": "Number of message packets sent",
"type": "integer"
},
"mailbox_len": {
"description": "Process mailbox size",
"type": "integer"
},
"heap_size": {
"description": "Process heap size with the unit of byte",
"type": "integer"
},
"reductions": {
"description": "Erlang reduction",
"type": "integer"
}
},
"type": "object"
},
"emqx_authz_api_mnesia.clientid_response_data": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rules_for_clientid"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/public.meta"
}
},
"type": "object"
},
"listeners.wss_required_bind(with_name)": {
"required": [
"bind",
"name",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"wss"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"name": {
"description": "Listener name",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"bind": {
"default": 8084,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
},
"ssl_options": {
"$ref": "#/components/schemas/broker.listener_wss_opts"
},
"websocket": {
"$ref": "#/components/schemas/broker.ws_opts"
}
},
"type": "object"
},
"zone.force_gc": {
"properties": {
"enable": {
"description": "Enable forced garbage collection.",
"type": "boolean"
},
"count": {
"description": "GC the process after this many received messages.",
"minimum": 0,
"type": "integer"
},
"bytes": {
"description": "GC the process after specified number of bytes have passed through.",
"example": "32MB",
"type": "string"
}
},
"type": "object"
},
"emqx_mgmt_api_nodes.node_info": {
"properties": {
"node": {
"description": "Node name",
"example": "emqx@127.0.0.1",
"type": "string"
},
"connections": {
"description": "Number of clients currently connected to this node",
"example": 0,
"minimum": 0,
"type": "integer"
},
"load1": {
"description": "CPU average load in 1 minute",
"example": 2.66,
"type": "number"
},
"load5": {
"description": "CPU average load in 5 minute",
"example": 2.66,
"type": "number"
},
"load15": {
"description": "CPU average load in 15 minute",
"example": 2.66,
"type": "number"
},
"max_fds": {
"description": "File descriptors limit",
"example": 1024,
"minimum": 0,
"type": "integer"
},
"memory_total": {
"description": "Allocated memory",
"example": "512.00M",
"type": "string"
},
"memory_used": {
"description": "Used memory",
"example": "256.00M",
"type": "string"
},
"node_status": {
"description": "Node status",
"enum": [
"running",
"stopped"
],
"example": "running",
"type": "string"
},
"otp_release": {
"description": "Erlang/OTP version",
"example": "24.2/12.2",
"type": "string"
},
"process_available": {
"description": "Erlang processes limit",
"example": 2097152,
"minimum": 0,
"type": "integer"
},
"process_used": {
"description": "Running Erlang processes",
"example": 1024,
"minimum": 0,
"type": "integer"
},
"uptime": {
"description": "System uptime, milliseconds",
"example": 5120000,
"minimum": 0,
"type": "integer"
},
"version": {
"description": "Release version",
"example": "5.0.0",
"type": "string"
},
"edition": {
"description": "Release edition",
"enum": [
"Opensource",
"Enterprise"
],
"example": "Opensource",
"type": "string"
},
"sys_path": {
"description": "Path to system files",
"example": "path/to/emqx",
"type": "string"
},
"log_path": {
"description": "Path to log files",
"example": "path/to/log | The log path is not yet set",
"type": "string"
},
"role": {
"description": "Node role",
"enum": [
"core",
"replicant"
],
"example": "core",
"type": "string"
}
},
"type": "object"
},
"emqx_delayed_api.message_without_payload": {
"properties": {
"msgid": {
"description": "Delayed Message ID",
"type": "integer"
},
"node": {
"description": "The node where message from",
"type": "string"
},
"publish_at": {
"description": "Clinet publish message time, in RFC 3339 format",
"type": "string"
},
"delayed_interval": {
"description": "Delayed interval(second)",
"minimum": 1,
"type": "integer"
},
"delayed_remaining": {
"description": "Delayed remaining(second)",
"minimum": 0,
"type": "integer"
},
"expected_at": {
"description": "Expect publish time, in RFC 3339 format",
"type": "string"
},
"topic": {
"description": "Topic",
"example": "/sys/#",
"type": "string"
},
"qos": {
"description": "QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
},
"from_clientid": {
"description": "From ClientID",
"type": "string"
},
"from_username": {
"description": "From Username",
"type": "string"
}
},
"type": "object"
},
"emqx_authz_api_mnesia.rules": {
"properties": {
"rules": {
"items": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rule_item"
},
"type": "array"
}
},
"type": "object"
},
"slow_subscribers_statistics.record": {
"properties": {
"clientid": {
"description": "Message clientid",
"type": "string"
},
"node": {
"description": "Message node name",
"type": "string"
},
"topic": {
"description": "Message topic",
"type": "string"
},
"timespan": {
"description": "Timespan for message transmission",
"type": "integer"
},
"last_update_time": {
"description": "The timestamp of last update",
"type": "integer"
}
},
"type": "object"
},
"emqx_gateway_api_clients.mqttsn_client": {
"properties": {
"node": {
"description": "Name of the node to which the client is connected",
"type": "string"
},
"clientid": {
"description": "Client ID",
"type": "string"
},
"username": {
"description": "Username of client when connecting",
"type": "string"
},
"mountpoint": {
"description": "Topic mountpoint",
"type": "string"
},
"proto_name": {
"description": "Client protocol name",
"type": "string"
},
"proto_ver": {
"description": "Protocol version used by the client",
"type": "string"
},
"ip_address": {
"description": "Client's IP address",
"type": "string"
},
"port": {
"description": "Client's port",
"type": "integer"
},
"is_bridge": {
"description": "Indicates whether the client is connected via bridge",
"type": "boolean"
},
"connected_at": {
"description": "Client connection time",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"disconnected_at": {
"description": "Client offline time, This field is only valid and returned when connected is false",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"connected": {
"description": "Whether the client is connected",
"type": "boolean"
},
"keepalive": {
"description": "Keepalive time, with the unit of second",
"type": "integer"
},
"clean_start": {
"description": "Indicate whether the client is using a brand new session",
"type": "boolean"
},
"expiry_interval": {
"description": "Session expiration interval, with the unit of second",
"type": "integer"
},
"created_at": {
"description": "Session creation time",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"subscriptions_cnt": {
"description": "Number of subscriptions established by this client",
"type": "integer"
},
"subscriptions_max": {
"description": "Maximum number of subscriptions allowed by this client",
"type": "integer"
},
"inflight_cnt": {
"description": "Current length of inflight",
"type": "integer"
},
"inflight_max": {
"description": "Maximum length of inflight",
"type": "integer"
},
"mqueue_len": {
"description": "Current length of message queue",
"type": "integer"
},
"mqueue_max": {
"description": "Maximum length of message queue",
"type": "integer"
},
"mqueue_dropped": {
"description": "Number of messages dropped by the message queue due to exceeding the length",
"type": "integer"
},
"awaiting_rel_cnt": {
"description": "Number of awaiting acknowledge packet",
"type": "integer"
},
"awaiting_rel_max": {
"description": "Maximum allowed number of awaiting PUBREC packet",
"type": "integer"
},
"recv_oct": {
"description": "Number of bytes received",
"type": "integer"
},
"recv_cnt": {
"description": "Number of socket packets received",
"type": "integer"
},
"recv_pkt": {
"description": "Number of protocol packets received",
"type": "integer"
},
"recv_msg": {
"description": "Number of message packets received",
"type": "integer"
},
"send_oct": {
"description": "Number of bytes sent",
"type": "integer"
},
"send_cnt": {
"description": "Number of socket packets sent",
"type": "integer"
},
"send_pkt": {
"description": "Number of protocol packets sent",
"type": "integer"
},
"send_msg": {
"description": "Number of message packets sent",
"type": "integer"
},
"mailbox_len": {
"description": "Process mailbox size",
"type": "integer"
},
"heap_size": {
"description": "Process heap size with the unit of byte",
"type": "integer"
},
"reductions": {
"description": "Erlang reduction",
"type": "integer"
}
},
"type": "object"
},
"emqx_topic_metrics_api.metrics": {
"properties": {
"message.dropped.count": {
"description": "Dropped messages count",
"example": 0,
"type": "integer"
},
"message.in.count": {
"description": "In messages count",
"example": 0,
"type": "integer"
},
"message.out.count": {
"description": "Out messages count",
"example": 0,
"type": "integer"
},
"message.qos0.in.count": {
"description": "QoS0 in messages count",
"example": 0,
"type": "integer"
},
"message.qos0.out.count": {
"description": "QoS0 out messages count",
"example": 0,
"type": "integer"
},
"message.qos1.in.count": {
"description": "QoS1 in messages count",
"example": 0,
"type": "integer"
},
"message.qos1.out.count": {
"description": "QoS1 out messages count",
"example": 0,
"type": "integer"
},
"message.qos2.in.count": {
"description": "QoS2 in messages count",
"example": 0,
"type": "integer"
},
"message.qos2.out.count": {
"description": "QoS2 out messages count",
"example": 0,
"type": "integer"
},
"message.dropped.rate": {
"description": "Dropped messages rate",
"example": 0,
"type": "number"
},
"message.in.rate": {
"description": "In messages rate",
"example": 0,
"type": "number"
},
"message.out.rate": {
"description": "Out messages rate",
"example": 0,
"type": "number"
},
"message.qos0.in.rate": {
"description": "QoS0 in messages rate",
"example": 0,
"type": "number"
},
"message.qos0.out.rate": {
"description": "QoS0 out messages rate",
"example": 0,
"type": "number"
},
"message.qos1.in.rate": {
"description": "QoS1 in messages rate",
"example": 0,
"type": "number"
},
"message.qos1.out.rate": {
"description": "QoS1 out messages rate",
"example": 0,
"type": "number"
},
"message.qos2.in.rate": {
"description": "QoS2 in messages rate",
"example": 0,
"type": "number"
},
"message.qos2.out.rate": {
"description": "QoS2 out messages rate",
"example": 0,
"type": "number"
}
},
"type": "object"
},
"listeners.ssl_not_required_bind": {
"required": [
"id",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"ssl"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"id": {
"description": "Listener id",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"bind": {
"default": 8883,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
},
"ssl_options": {
"$ref": "#/components/schemas/broker.listener_ssl_opts"
}
},
"type": "object"
},
"emqx_gateway_api.update_lwm2m": {
"required": [
"translators",
"xml_dir"
],
"properties": {
"xml_dir": {
"description": "The Directory for LwM2M Resource definition.",
"example": "/etc/emqx/lwm2m_xml",
"type": "string"
},
"lifetime_min": {
"default": "15s",
"description": "Minimum value of lifetime allowed to be set by the LwM2M client.",
"example": "12m",
"type": "string"
},
"lifetime_max": {
"default": "86400s",
"description": "Maximum value of lifetime allowed to be set by the LwM2M client.",
"example": "12m",
"type": "string"
},
"qmode_time_window": {
"default": "22s",
"description": "The value of the time window during which the network link is considered valid by the LwM2M Gateway in QMode mode.
For example, after receiving an update message from a client, any messages within this time window are sent directly to the LwM2M client, and all messages beyond this time window are temporarily stored in memory.",
"example": "1h",
"type": "string"
},
"auto_observe": {
"default": false,
"description": "Automatically observe the object list of REGISTER packet.",
"type": "boolean"
},
"update_msg_publish_condition": {
"default": "contains_object_list",
"description": "Policy for publishing UPDATE event message.
- always: send update events as long as the UPDATE request is received.
- contains_object_list: send update events only if the UPDATE request carries any Object List
",
"enum": [
"always",
"contains_object_list"
],
"type": "string"
},
"translators": {
"description": "Topic configuration for LwM2M's gateway publishing and subscription.",
"$ref": "#/components/schemas/gateway.lwm2m_translators"
},
"mountpoint": {
"default": "lwm2m/${endpoint_name}/",
"description": " ",
"type": "string"
},
"enable": {
"default": true,
"description": "Whether to enable this gateway",
"type": "boolean"
},
"enable_stats": {
"default": true,
"description": "Whether to enable client process statistic",
"type": "boolean"
},
"idle_timeout": {
"default": "30s",
"description": "The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.",
"example": "12m",
"type": "string"
},
"clientinfo_override": {
"description": "ClientInfo override.",
"$ref": "#/components/schemas/gateway.clientinfo_override"
}
},
"type": "object"
},
"emqx_rule_api_schema.ctx_bridge_mqtt": {
"required": [
"event_type"
],
"properties": {
"event_type": {
"description": "Event Type",
"enum": [
"$bridges/mqtt:*"
],
"type": "string"
},
"id": {
"description": "Message ID",
"type": "string"
},
"payload": {
"description": "The Message Payload",
"type": "string"
},
"topic": {
"description": "Message Topic",
"type": "string"
},
"server": {
"description": "The IP address (or hostname) and port of the MQTT broker, in IP:Port format",
"type": "string"
},
"dup": {
"description": "The DUP flag of the MQTT message",
"type": "string"
},
"retain": {
"description": "If is a retain message",
"type": "string"
},
"message_received_at": {
"description": "The Time that this Message is Received",
"type": "integer"
},
"qos": {
"description": "The Message QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"emqx_rule_api_schema.ctx_delivered": {
"required": [
"event_type"
],
"properties": {
"event_type": {
"description": "Event Type",
"enum": [
"message_delivered"
],
"type": "string"
},
"id": {
"description": "Message ID",
"type": "string"
},
"from_clientid": {
"description": "The Client ID",
"type": "string"
},
"from_username": {
"description": "The User Name",
"type": "string"
},
"clientid": {
"description": "The Client ID",
"type": "string"
},
"username": {
"description": "The User Name",
"type": "string"
},
"payload": {
"description": "The Message Payload",
"type": "string"
},
"peerhost": {
"description": "The IP Address of the Peer Client",
"type": "string"
},
"topic": {
"description": "Message Topic",
"type": "string"
},
"publish_received_at": {
"description": "The Time that this Message is Received",
"type": "integer"
},
"qos": {
"description": "The Message QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"emqx_conf_schema.cluster_dns": {
"properties": {
"name": {
"default": "localhost",
"description": "The domain name from which to discover peer EMQX nodes' IP addresses.
Applicable when cluster.discovery_strategy = dns
",
"readOnly": true,
"type": "string"
},
"record_type": {
"default": "a",
"description": "DNS record type. ",
"enum": [
"a",
"srv"
],
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"modules.delayed": {
"properties": {
"enable": {
"default": true,
"description": "Enable this feature",
"type": "boolean"
},
"max_delayed_messages": {
"default": 0,
"description": "Maximum number of delayed messages (0 is no limit).",
"type": "integer"
}
},
"type": "object"
},
"emqx_connector_mongo.topology": {
"properties": {
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"max_overflow": {
"default": 0,
"description": "Max Overflow.",
"minimum": 0,
"type": "integer"
},
"overflow_ttl": {
"description": "Period of time before workers that exceed the configured pool size (\"overflow\") to be terminated.",
"example": "32s",
"type": "string"
},
"overflow_check_period": {
"description": "Period for checking if there are more workers than configured (\"overflow\").",
"example": "32s",
"type": "string"
},
"local_threshold_ms": {
"description": "The size of the latency window for selecting among multiple suitable MongoDB instances.",
"example": "32s",
"type": "string"
},
"connect_timeout_ms": {
"description": "The duration to attempt a connection before timing out.",
"example": "32s",
"type": "string"
},
"socket_timeout_ms": {
"description": "The duration to attempt to send or to receive on a socket before the attempt times out.",
"example": "32s",
"type": "string"
},
"server_selection_timeout_ms": {
"description": "Specifies how long to block for server selection before throwing an exception.",
"example": "32s",
"type": "string"
},
"wait_queue_timeout_ms": {
"description": "The maximum duration that a worker can wait for a connection to become available.",
"example": "32s",
"type": "string"
},
"heartbeat_frequency_ms": {
"description": "Controls when the driver checks the state of the MongoDB deployment. Specify the interval between checks, counted from the end of the previous check until the beginning of the next one.",
"example": "32s",
"type": "string"
},
"min_heartbeat_frequency_ms": {
"description": "Controls the minimum amount of time to wait between heartbeats.",
"example": "32s",
"type": "string"
}
},
"type": "object"
},
"plugins.builder": {
"properties": {
"contact": {
"example": "emqx-support@emqx.io",
"type": "string"
},
"name": {
"example": "EMQX Team",
"type": "string"
},
"website": {
"example": "www.emqx.com",
"type": "string"
}
},
"type": "object"
},
"retainer.flow_control": {
"properties": {
"batch_read_number": {
"default": 0,
"description": "Size of the batch when reading messages from storage. 0 means no limit.",
"minimum": 0,
"type": "integer"
},
"batch_deliver_number": {
"default": 0,
"description": "The number of retained messages can be delivered per batch.",
"maximum": 1000,
"minimum": 0,
"type": "integer"
},
"batch_deliver_limiter": {
"description": "The rate limiter name for retained messages' delivery.
Limiter helps to avoid delivering too many messages to the client at once, which may cause the client to block or crash, or drop messages due to exceeding the size of the message queue.
The names of the available rate limiters are taken from the existing rate limiters under `limiter.batch`.
If this field is empty, limiter is not used.",
"$ref": "#/components/schemas/limiter.internal"
}
},
"type": "object"
},
"exhook.hook_info": {
"properties": {
"name": {
"description": "The hook's name",
"type": "string"
},
"params": {
"description": "The parameters used when the hook is registered",
"properties": {
"$name": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"authn-redis.cluster": {
"required": [
"servers",
"cmd",
"backend",
"mechanism"
],
"properties": {
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"password_based"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"redis"
],
"type": "string"
},
"cmd": {
"description": "The Redis Command used to query data for authentication such as password hash, currently only supports HGET and HMGET.",
"type": "string"
},
"password_hash_algorithm": {
"default": {
"name": "sha256",
"salt_position": "prefix"
},
"description": "Options for password hash verification.",
"oneOf": [
{
"$ref": "#/components/schemas/authn-hash.other_algorithms"
},
{
"$ref": "#/components/schemas/authn-hash.pbkdf2"
},
{
"$ref": "#/components/schemas/authn-hash.bcrypt"
}
]
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
},
"servers": {
"description": "
A Node list for Cluster to connect to. The nodes should be separated with commas, such as: `Node[,Node].`
For each Node should be: The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The Redis default port 6379 is used if `[:Port]` is not specified.
",
"type": "string"
},
"redis_type": {
"default": "cluster",
"description": "Cluster mode. Must be set to 'cluster' when Redis server is running in clustered mode.",
"enum": [
"cluster"
],
"type": "string"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auto_reconnect": {
"default": true,
"deprecated": "since(\"v5.0.15\")",
"description": "Deprecated. Enable automatic reconnect to the database.",
"type": "boolean"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"limiter.listener_fields": {
"properties": {
"bytes_in": {
"description": "The bytes_in limiter.
This is used to limit the inbound bytes rate for this EMQX node.
Once the limit is reached, the restricted client will be slow down even be hung for a while.",
"$ref": "#/components/schemas/limiter.bucket_opts"
},
"message_in": {
"description": "The message in limiter.
This is used to limit the inbound message numbers for this EMQX node
Once the limit is reached, the restricted client will be slow down even be hung for a while.",
"$ref": "#/components/schemas/limiter.bucket_opts"
},
"connection": {
"description": "The connection limiter.
This is used to limit the connection rate for this EMQX node.
Once the limit is reached, new connections will be refused",
"$ref": "#/components/schemas/limiter.bucket_opts"
},
"message_routing": {
"description": "The message routing limiter.
This is used to limit the forwarding rate for this EMQX node.
Once the limit is reached, new publish will be refused",
"$ref": "#/components/schemas/limiter.bucket_opts"
},
"client": {
"description": "The rate limit for each user of the bucket",
"$ref": "#/components/schemas/limiter.listener_client_fields"
}
},
"type": "object"
},
"emqx_conf_schema.log_file_handler": {
"properties": {
"file": {
"description": "Name the log file.",
"example": "/path/to/file",
"type": "string"
},
"rotation": {
"$ref": "#/components/schemas/emqx_conf_schema.log_rotation"
},
"max_size": {
"default": "50MB",
"description": "This parameter controls log file rotation. The value `infinity` means the log file will grow indefinitely, otherwise the log file will be rotated once it reaches `max_size` in bytes.",
"oneOf": [
{
"example": "32MB",
"type": "string"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"enable": {
"default": true,
"description": "Enable this log handler.",
"type": "boolean"
},
"level": {
"default": "warning",
"description": "
The log level for the current log handler.
Defaults to warning.
",
"enum": [
"debug",
"info",
"notice",
"warning",
"error",
"critical",
"alert",
"emergency",
"all"
],
"type": "string"
},
"time_offset": {
"default": "system",
"description": "
The time offset to be used when formatting the timestamp.
Can be one of:
- system: the time offset used by the local system
- utc: the UTC time offset
- +-[hh]:[mm]: user specified time offset, such as \"-02:00\" or \"+00:00\"
Defaults to: system.
",
"type": "string"
},
"chars_limit": {
"default": "unlimited",
"description": "
Set the maximum length of a single log message. If this length is exceeded, the log message will be truncated.
NOTE: Restrict char limiter if formatter is JSON , it will get a truncated incomplete JSON data, which is not recommended.
",
"oneOf": [
{
"minimum": 100,
"type": "integer"
},
{
"enum": [
"unlimited"
],
"type": "string"
}
]
},
"formatter": {
"default": "text",
"description": "Choose log formatter. text for free text, and json for structured logging.",
"enum": [
"text",
"json"
],
"type": "string"
},
"single_line": {
"default": true,
"description": "Print logs in a single line if set to true. Otherwise, log messages may span multiple lines.",
"type": "boolean"
},
"sync_mode_qlen": {
"default": 100,
"description": "As long as the number of buffered log events is lower than this value,
all log events are handled asynchronously. This means that the client process sending the log event,
by calling a log function in the Logger API, does not wait for a response from the handler
but continues executing immediately after the event is sent.
It is not affected by the time it takes the handler to print the event to the log device.
If the message queue grows larger than this value,
the handler starts handling log events synchronously instead,
meaning that the client process sending the event must wait for a response.
When the handler reduces the message queue to a level below the sync_mode_qlen threshold,
asynchronous operation is resumed.
",
"minimum": 0,
"type": "integer"
},
"drop_mode_qlen": {
"default": 3000,
"description": "When the number of buffered log events is larger than this value, the new log events are dropped.
When drop mode is activated or deactivated, a message is printed in the logs.",
"minimum": 1,
"type": "integer"
},
"flush_qlen": {
"default": 8000,
"description": "If the number of buffered log events grows larger than this threshold, a flush (delete) operation takes place.
To flush events, the handler discards the buffered log messages without logging.",
"minimum": 1,
"type": "integer"
},
"overload_kill": {
"$ref": "#/components/schemas/emqx_conf_schema.log_overload_kill"
},
"burst_limit": {
"$ref": "#/components/schemas/emqx_conf_schema.log_burst_limit"
},
"supervisor_reports": {
"default": "error",
"description": "
Type of supervisor reports that are logged. Defaults to error
- error: only log errors in the Erlang processes.
- progress: log process startup.
",
"enum": [
"error",
"progress"
],
"type": "string"
},
"max_depth": {
"default": 100,
"description": "Maximum depth for Erlang term log formatting and Erlang process message queue inspection.",
"oneOf": [
{
"minimum": 0,
"type": "integer"
},
{
"enum": [
"unlimited"
],
"type": "string"
}
]
}
},
"type": "object"
},
"retainer.retainer": {
"properties": {
"enable": {
"default": true,
"description": "Enable retainer feature",
"type": "boolean"
},
"msg_expiry_interval": {
"default": "0s",
"description": "Message retention time. 0 means message will never be expired.",
"example": "32s",
"type": "string"
},
"msg_clear_interval": {
"default": "0s",
"description": "Periodic interval for cleaning up expired messages.
Never clear if the value is 0.
",
"example": "32s",
"type": "string"
},
"flow_control": {
"default": {},
"description": "Flow control.",
"$ref": "#/components/schemas/retainer.flow_control"
},
"max_payload_size": {
"default": "1MB",
"description": "Maximum retained message size.",
"example": "32MB",
"type": "string"
},
"stop_publish_clear_msg": {
"default": false,
"description": "When the retained flag of the `PUBLISH` message is set and Payload is empty,
whether to continue to publish the message.
See:
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718038",
"type": "boolean"
},
"backend": {
"description": "Settings for the database storing the retained messages.",
"$ref": "#/components/schemas/retainer.mnesia_config"
}
},
"type": "object"
},
"emqx_authz_api_schema.position": {
"required": [
"position"
],
"properties": {
"position": {
"description": "Where to place the source.",
"type": "string"
}
},
"type": "object"
},
"authn-jwt.hmac-based": {
"required": [
"mechanism",
"secret",
"algorithm",
"use_jwks"
],
"properties": {
"use_jwks": {
"description": "Whether to use JWKS.",
"enum": [
false
],
"type": "string"
},
"algorithm": {
"description": "JWT signing algorithm, Supports HMAC (configured as hmac-based) and RSA, ECDSA (configured as public-key).",
"enum": [
"hmac-based"
],
"type": "string"
},
"secret": {
"description": "The key to verify the JWT using HMAC algorithm.",
"type": "string"
},
"secret_base64_encoded": {
"default": false,
"description": "Whether secret is base64 encoded.",
"type": "boolean"
},
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"jwt"
],
"type": "string"
},
"acl_claim_name": {
"default": "acl",
"description": "JWT claim name to use for getting ACL rules.",
"type": "string"
},
"verify_claims": {
"default": {},
"description": "
A list of custom claims to validate, which is a list of name/value pairs.
Values can use the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
Authentication will verify that the value of claims in the JWT (taken from the Password field) matches what is required in verify_claims.
",
"items": {
"example": "any",
"type": "string"
},
"type": "array"
},
"from": {
"default": "password",
"description": "Field to take JWT from.",
"enum": [
"username",
"password"
],
"type": "string"
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
}
},
"type": "object"
},
"zone.flapping_detect": {
"properties": {
"enable": {
"description": "Enable flapping connection detection feature.",
"type": "boolean"
},
"max_count": {
"description": "The maximum number of disconnects allowed for a MQTT Client in `window_time`",
"type": "integer"
},
"window_time": {
"description": "The time window for flapping detection.",
"example": "12m",
"type": "string"
},
"ban_time": {
"description": "How long the flapping clientid will be banned.",
"example": "12m",
"type": "string"
}
},
"type": "object"
},
"emqx_rule_api_schema.node_metrics": {
"properties": {
"node": {
"description": "The node name",
"example": "emqx@127.0.0.1",
"type": "string"
},
"matched": {
"description": "How much times the FROM clause of the SQL is matched.",
"minimum": 0,
"type": "integer"
},
"matched.rate": {
"description": "The rate of matched, times/second",
"type": "number"
},
"matched.rate.max": {
"description": "The max rate of matched, times/second",
"type": "number"
},
"matched.rate.last5m": {
"description": "The average rate of matched in last 5 minutes, times/second",
"type": "number"
},
"passed": {
"description": "How much times the SQL is passed",
"minimum": 0,
"type": "integer"
},
"failed": {
"description": "How much times the SQL is failed",
"minimum": 0,
"type": "integer"
},
"failed.exception": {
"description": "How much times the SQL is failed due to exceptions. This may because of a crash when calling a SQL function, or trying to do arithmetic operation on undefined variables",
"minimum": 0,
"type": "integer"
},
"failed.unknown": {
"description": "How much times the SQL is failed due to an unknown error.",
"minimum": 0,
"type": "integer"
},
"actions.total": {
"description": "How much times the actions are called by the rule. This value may several times of 'matched', depending on the number of the actions of the rule.",
"minimum": 0,
"type": "integer"
},
"actions.success": {
"description": "How much times the rule success to call the actions.",
"minimum": 0,
"type": "integer"
},
"actions.failed": {
"description": "How much times the rule failed to call the actions.",
"minimum": 0,
"type": "integer"
},
"actions.failed.out_of_service": {
"description": "How much times the rule failed to call actions due to the action is out of service. For example, a bridge is disabled or stopped.",
"minimum": 0,
"type": "integer"
},
"actions.failed.unknown": {
"description": "How much times the rule failed to call actions due to to an unknown error.",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"zone.stats": {
"properties": {
"enable": {
"description": "Enable/disable statistic data collection.",
"type": "boolean"
}
},
"type": "object"
},
"authn-mongodb.replica-set": {
"required": [
"database",
"replica_set_name",
"servers",
"collection",
"backend",
"mechanism"
],
"properties": {
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"password_based"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"mongodb"
],
"type": "string"
},
"collection": {
"description": "Collection used to store authentication data.",
"type": "string"
},
"filter": {
"default": {},
"description": "
Conditional expression that defines the filter condition in the query.
Filter supports the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
",
"example": {},
"type": "object"
},
"password_hash_field": {
"default": "password_hash",
"description": "Document field that contains password hash.",
"type": "string"
},
"salt_field": {
"default": "salt",
"description": "Document field that contains the password salt.",
"type": "string"
},
"is_superuser_field": {
"default": "is_superuser",
"description": "Document field that defines if the user has superuser privileges.",
"type": "string"
},
"password_hash_algorithm": {
"default": {
"name": "sha256",
"salt_position": "prefix"
},
"description": "Options for password hash verification.",
"oneOf": [
{
"$ref": "#/components/schemas/authn-hash.other_algorithms"
},
{
"$ref": "#/components/schemas/authn-hash.pbkdf2"
},
{
"$ref": "#/components/schemas/authn-hash.bcrypt"
}
]
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
},
"mongo_type": {
"default": "rs",
"description": "Replica set. Must be set to 'rs' when MongoDB server is running in 'replica set' mode.",
"enum": [
"rs"
],
"type": "string"
},
"servers": {
"description": "
A Node list for Cluster to connect to. The nodes should be separated with commas, such as: `Node[,Node].`
For each Node should be: The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The MongoDB default port 27017 is used if `[:Port]` is not specified.
",
"type": "string"
},
"w_mode": {
"default": "unsafe",
"description": "Write mode.",
"enum": [
"unsafe",
"safe"
],
"type": "string"
},
"r_mode": {
"default": "master",
"description": "Read mode.",
"enum": [
"master",
"slave_ok"
],
"type": "string"
},
"replica_set_name": {
"description": "Name of the replica set.",
"type": "string"
},
"srv_record": {
"default": false,
"description": "Use DNS SRV record.",
"type": "boolean"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"username": {
"description": "EMQX's username in the external database.",
"type": "string"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auth_source": {
"description": "Database name associated with the user's credentials.",
"type": "string"
},
"database": {
"description": "Database name.",
"type": "string"
},
"topology": {
"$ref": "#/components/schemas/emqx_connector_mongo.topology"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"exhook.node_metrics": {
"properties": {
"node": {
"description": "Node name",
"type": "string"
},
"metrics": {
"description": "Metrics information",
"$ref": "#/components/schemas/exhook.metrics"
}
},
"type": "object"
},
"exhook.move_req": {
"required": [
"position"
],
"properties": {
"position": {
"description": "The target position to be moved",
"example": "front",
"type": "string"
}
},
"type": "object"
},
"broker.zone": {
"properties": {
"mqtt": {
"description": "Global MQTT configuration.
The configs here work as default values which can be overridden
in zone configs",
"$ref": "#/components/schemas/zone.mqtt"
},
"stats": {
"description": "Enable/disable statistic data collection.
Statistic data such as message receive/send count/rate etc. It provides insights of system performance and helps to diagnose issues. You can find statistic data from the dashboard, or from the '/stats' API.",
"$ref": "#/components/schemas/zone.stats"
},
"flapping_detect": {
"description": "This config controls the allowed maximum number of `CONNECT` packets received
from the same clientid in a time frame defined by `window_time`.
After the limit is reached, successive `CONNECT` requests are forbidden
(banned) until the end of the time period defined by `ban_time`.",
"$ref": "#/components/schemas/zone.flapping_detect"
},
"force_shutdown": {
"description": "When the process message queue length, or the memory bytes
reaches a certain value, the process is forced to close.
Note: \"message queue\" here refers to the \"message mailbox\"
of the Erlang process, not the `mqueue` of QoS 1 and QoS 2.",
"$ref": "#/components/schemas/zone.force_shutdown"
},
"conn_congestion": {
"description": "Settings for `conn_congestion` alarm.
Sometimes the MQTT connection (usually an MQTT subscriber) may
get \"congested\", because there are too many packets to be sent.
The socket tries to buffer the packets until the buffer is
full. If more packets arrive after that, the packets will be
\"pending\" in the queue, and we consider the connection
congested.
Note: `sndbuf` can be set to larger value if the
alarm is triggered too often.
The name of the alarm is of format `conn_congestion//`,
where the `` is the client ID of the congested MQTT connection,
and `` is the username or `unknown_user`.",
"$ref": "#/components/schemas/zone.conn_congestion"
},
"force_gc": {
"description": "Force garbage collection in MQTT connection process after
they process certain number of messages or bytes of data.",
"$ref": "#/components/schemas/zone.force_gc"
},
"overload_protection": {
"description": "Overload protection mechanism monitors the load of the system and temporarily
disables some features (such as accepting new connections) when the load is high.",
"$ref": "#/components/schemas/zone.overload_protection"
}
},
"type": "object"
},
"emqx_conf_schema.log_overload_kill": {
"properties": {
"enable": {
"default": true,
"description": "Enable log handler overload kill feature.",
"type": "boolean"
},
"mem_size": {
"default": "30MB",
"description": "Maximum memory size that the log handler process is allowed to use.",
"example": "32MB",
"type": "string"
},
"qlen": {
"default": 20000,
"description": "Maximum allowed queue length.",
"minimum": 1,
"type": "integer"
},
"restart_after": {
"default": "5s",
"description": "The handler restarts automatically after a delay in the event of termination, unless the value `infinity` is set, which blocks any subsequent restarts.",
"oneOf": [
{
"enum": [
"infinity"
],
"type": "string"
},
{
"example": "32s",
"type": "string"
}
]
}
},
"type": "object"
},
"exhook.node_status": {
"properties": {
"node": {
"description": "Node name",
"type": "string"
},
"status": {
"description": "The status of Exhook server.
connected: connection succeeded
connecting: connection failed, reconnecting
disconnected: failed to connect and didn't reconnect
disabled: this server is disabled
error: failed to view the status of this server
",
"enum": [
"connected",
"connecting",
"disconnected",
"disabled",
"error"
],
"type": "string"
}
},
"type": "object"
},
"emqx_rule_api_schema.rule_creation": {
"required": [
"sql"
],
"properties": {
"name": {
"default": "",
"description": "The name of the rule",
"example": "foo",
"type": "string"
},
"sql": {
"description": "
SQL query to transform the messages.
Example: SELECT * FROM \"test/topic\" WHERE payload.x = 1
",
"example": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
"type": "string"
},
"actions": {
"default": "",
"description": "
A list of actions of the rule.
An action can be a string that refers to the channel ID of an EMQX bridge, or an object
that refers to a function.
There a some built-in functions like \"republish\" and \"console\", and we also support user
provided functions in the format: \"{module}:{function}\".
The actions in the list are executed sequentially.
This means that if one of the action is executing slowly, all the following actions will not
be executed until it returns.
If one of the action crashed, all other actions come after it will still be executed, in the
original order.
If there's any error when running an action, there will be an error message, and the 'failure'
counter of the function action or the bridge channel will increase.
",
"example": [
"webhook:my_webhook",
{
"args": {
"payload": "${payload}",
"topic": "t/1"
},
"function": "republish"
},
{
"function": "console"
}
],
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/rule_engine.user_provided_function"
},
{
"$ref": "#/components/schemas/rule_engine.builtin_action_console"
},
{
"$ref": "#/components/schemas/rule_engine.builtin_action_republish"
},
{
"type": "string"
}
]
},
"type": "array"
},
"enable": {
"default": true,
"description": "Enable or disable the rule",
"type": "boolean"
},
"description": {
"default": "",
"description": "The description of the rule",
"example": "Some description",
"type": "string"
},
"metadata": {
"description": "Rule metadata, do not change manually",
"example": {},
"type": "object"
}
},
"type": "object"
},
"listeners.ws_required_bind": {
"required": [
"bind",
"id",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"ws"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"id": {
"description": "Listener id",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"bind": {
"default": 8083,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
},
"websocket": {
"$ref": "#/components/schemas/broker.ws_opts"
}
},
"type": "object"
},
"broker.persistent_session_builtin": {
"properties": {
"type": {
"default": "builtin",
"description": "",
"enum": [
"builtin"
],
"type": "string"
},
"session": {
"description": "Performance tuning options for built-in session table.",
"$ref": "#/components/schemas/broker.persistent_table_mria_opts"
},
"session_messages": {
"description": "Performance tuning options for built-in session messages table.",
"$ref": "#/components/schemas/broker.persistent_table_mria_opts"
},
"messages": {
"description": "Performance tuning options for built-in messages table.",
"$ref": "#/components/schemas/broker.persistent_table_mria_opts"
}
},
"type": "object"
},
"listeners.listener_type_status": {
"required": [
"ids",
"enable",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"tcp",
"ssl",
"ws",
"wss",
"quic"
],
"type": "string"
},
"enable": {
"description": "Listener enable",
"type": "boolean"
},
"ids": {
"description": "Listener Ids",
"items": {
"type": "string"
},
"type": "array"
},
"status": {
"$ref": "#/components/schemas/listeners.status"
},
"node_status": {
"items": {
"$ref": "#/components/schemas/listeners.node_status"
},
"type": "array"
}
},
"type": "object"
},
"emqx_authz_api_schema.redis_sentinel": {
"required": [
"database",
"sentinel",
"servers",
"cmd",
"type"
],
"properties": {
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "redis",
"description": "Backend type.",
"enum": [
"redis"
],
"type": "string"
},
"cmd": {
"description": "Database query used to retrieve authorization data.",
"example": "HGETALL mqtt_authz",
"type": "string"
},
"servers": {
"description": "
A Node list for Cluster to connect to. The nodes should be separated with commas, such as: `Node[,Node].`
For each Node should be: The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The Redis default port 6379 is used if `[:Port]` is not specified.
",
"type": "string"
},
"redis_type": {
"default": "sentinel",
"description": "Sentinel mode. Must be set to 'sentinel' when Redis server is running in sentinel mode.",
"enum": [
"sentinel"
],
"type": "string"
},
"sentinel": {
"description": "The cluster name in Redis sentinel mode.",
"type": "string"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"database": {
"default": 0,
"description": "Redis database ID.",
"type": "integer"
},
"auto_reconnect": {
"default": true,
"deprecated": "since(\"v5.0.15\")",
"description": "Deprecated. Enable automatic reconnect to the database.",
"type": "boolean"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"gateway.translator": {
"required": [
"topic"
],
"properties": {
"topic": {
"description": "Topic Name",
"type": "string"
},
"qos": {
"default": 0,
"description": "QoS Level",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"emqx_authz_api_schema.mysql": {
"required": [
"database",
"server",
"query",
"type"
],
"properties": {
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "mysql",
"description": "Backend type.",
"enum": [
"mysql"
],
"type": "string"
},
"query": {
"description": "Database query used to retrieve authorization data.",
"type": "string"
},
"server": {
"description": "
The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The MySQL default port 3306 is used if `[:Port]` is not specified.
",
"type": "string"
},
"database": {
"description": "Database name.",
"type": "string"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"username": {
"default": "root",
"description": "EMQX's username in the external database.",
"type": "string"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auto_reconnect": {
"default": true,
"deprecated": "since(\"v5.0.15\")",
"description": "Deprecated. Enable automatic reconnect to the database.",
"type": "boolean"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"emqx_mgmt_api_stats.aggergate_data": {
"properties": {
"node": {
"description": "Node name",
"example": "emqx@127.0.0.1",
"type": "string"
},
"channels.count": {
"description": "sessions.count",
"example": 0,
"minimum": 0,
"type": "integer"
},
"channels.max": {
"description": "session.max",
"example": 0,
"minimum": 0,
"type": "integer"
},
"connections.count": {
"description": "Number of current connections",
"example": 0,
"minimum": 0,
"type": "integer"
},
"connections.max": {
"description": "Historical maximum number of connections",
"example": 0,
"minimum": 0,
"type": "integer"
},
"delayed.count": {
"description": "Number of delayed messages",
"example": 0,
"minimum": 0,
"type": "integer"
},
"delayed.max": {
"description": "Historical maximum number of delayed messages",
"example": 0,
"minimum": 0,
"type": "integer"
},
"live_connections.count": {
"description": "Number of current live connections",
"example": 0,
"minimum": 0,
"type": "integer"
},
"live_connections.max": {
"description": "Historical maximum number of live connections",
"example": 0,
"minimum": 0,
"type": "integer"
},
"retained.count": {
"description": "Number of currently retained messages",
"example": 0,
"minimum": 0,
"type": "integer"
},
"retained.max": {
"description": "Historical maximum number of retained messages",
"example": 0,
"minimum": 0,
"type": "integer"
},
"sessions.count": {
"description": "Number of current sessions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"sessions.max": {
"description": "Historical maximum number of sessions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"suboptions.count": {
"description": "subscriptions.count",
"example": 0,
"minimum": 0,
"type": "integer"
},
"suboptions.max": {
"description": "subscriptions.max",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscribers.count": {
"description": "Number of current subscribers",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscribers.max": {
"description": "Historical maximum number of subscribers",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscriptions.count": {
"description": "Number of current subscriptions, including shared subscriptions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscriptions.max": {
"description": "Historical maximum number of subscriptions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscriptions.shared.count": {
"description": "Number of current shared subscriptions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"subscriptions.shared.max": {
"description": "Historical maximum number of shared subscriptions",
"example": 0,
"minimum": 0,
"type": "integer"
},
"topics.count": {
"description": "Number of current topics",
"example": 0,
"minimum": 0,
"type": "integer"
},
"topics.max": {
"description": "Historical maximum number of topics",
"example": 0,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"authn-redis.standalone": {
"required": [
"database",
"server",
"cmd",
"backend",
"mechanism"
],
"properties": {
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"password_based"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"redis"
],
"type": "string"
},
"cmd": {
"description": "The Redis Command used to query data for authentication such as password hash, currently only supports HGET and HMGET.",
"type": "string"
},
"password_hash_algorithm": {
"default": {
"name": "sha256",
"salt_position": "prefix"
},
"description": "Options for password hash verification.",
"oneOf": [
{
"$ref": "#/components/schemas/authn-hash.other_algorithms"
},
{
"$ref": "#/components/schemas/authn-hash.pbkdf2"
},
{
"$ref": "#/components/schemas/authn-hash.bcrypt"
}
]
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
},
"server": {
"description": "
The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The Redis default port 6379 is used if `[:Port]` is not specified.
",
"type": "string"
},
"redis_type": {
"default": "single",
"description": "Single mode. Must be set to 'single' when Redis server is running in single mode.",
"enum": [
"single"
],
"type": "string"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"database": {
"default": 0,
"description": "Redis database ID.",
"type": "integer"
},
"auto_reconnect": {
"default": true,
"deprecated": "since(\"v5.0.15\")",
"description": "Deprecated. Enable automatic reconnect to the database.",
"type": "boolean"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"gateway.ssl_server_opts": {
"properties": {
"cacertfile": {
"description": "
Trusted PEM format CA certificates bundle file.
The certificates in this file are used to verify the TLS peer's certificates.
Append new certificates to the file if new CAs are to be trusted.
There is no need to restart EMQX to have the updated file loaded, because
the system regularly checks if file has been updated (and reload).
NOTE: invalidating (deleting) a certificate from the file will not affect
already established connections.
",
"type": "string"
},
"certfile": {
"description": "
PEM format certificates chain file.
The certificates in this file should be in reversed order of the certificate
issue chain. That is, the host's certificate should be placed in the beginning
of the file, followed by the immediate issuer certificate and so on.
Although the root CA certificate is optional, it should be placed at the end of
the file if it is to be added.
",
"type": "string"
},
"keyfile": {
"description": "PEM format private key file. ",
"type": "string"
},
"verify": {
"default": "verify_none",
"description": "Enable or disable peer verification. ",
"enum": [
"verify_peer",
"verify_none"
],
"type": "string"
},
"reuse_sessions": {
"default": true,
"description": "Enable TLS session reuse. ",
"type": "boolean"
},
"depth": {
"default": 10,
"description": "
Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path.
So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly;
if 1 the path can be PEER, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
",
"type": "integer"
},
"password": {
"description": "
String containing the user's password.
Only used if the private key file is password-protected.
",
"example": "",
"format": "password",
"type": "string"
},
"versions": {
"default": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
],
"description": "
All TLS/DTLS versions to be supported.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
In case PSK cipher suites are intended, make sure to configure
['tlsv1.2', 'tlsv1.1'] here.
",
"items": {
"type": "string"
},
"type": "array"
},
"ciphers": {
"default": "",
"description": "
This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\" or
[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"].
Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.
The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.
NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
PSK cipher suites: \"RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA\"
",
"items": {
"type": "string"
},
"type": "array"
},
"user_lookup_fun": {
"default": "emqx_tls_psk:lookup",
"description": "EMQX-internal callback that is used to lookup pre-shared key (PSK) identity. ",
"type": "string"
},
"secure_renegotiate": {
"default": true,
"description": "
SSL parameter renegotiation is a feature that allows a client and a server
to renegotiate the parameters of the SSL connection on the fly.
RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation,
you drop support for the insecure renegotiation, prone to MitM attacks.
",
"type": "boolean"
},
"dhfile": {
"description": "
Path to a file containing PEM-encoded Diffie-Hellman parameters
to be used by the server if a cipher suite using Diffie-Hellman
key exchange is negotiated. If not specified, default parameters
are used.
NOTE: The dhfile option is not supported by TLS 1.3.
",
"type": "string"
},
"fail_if_no_peer_cert": {
"default": false,
"description": "
Used together with {verify, verify_peer} by an TLS/DTLS server.
If set to true, the server fails if the client does not have a
certificate to send, that is, sends an empty certificate.
If set to false, it fails only if the client sends an invalid
certificate (an empty certificate is considered valid).
",
"type": "boolean"
},
"honor_cipher_order": {
"default": true,
"description": "
An important security setting, it forces the cipher to be set based
on the server-specified order instead of the client-specified order,
hence enforcing the (usually more properly configured) security
ordering of the server administrator.
",
"type": "boolean"
},
"client_renegotiation": {
"default": true,
"description": "
In protocols that support client-initiated renegotiation,
the cost of resources of such an operation is higher for the server than the client.
This can act as a vector for denial of service attacks.
The SSL application already takes measures to counter-act such attempts,
but client-initiated renegotiation can be strictly disabled by setting this option to false.
The default value is true. Note that disabling renegotiation can result in
long-lived connections becoming unusable due to limits on
the number of messages the underlying cipher suite can encipher.
",
"type": "boolean"
},
"handshake_timeout": {
"default": "15s",
"description": "
Maximum time duration allowed for the handshake to complete
",
"example": "12m",
"type": "string"
}
},
"type": "object"
},
"authn-jwt.public-key": {
"required": [
"mechanism",
"algorithm",
"use_jwks"
],
"properties": {
"use_jwks": {
"description": "Whether to use JWKS.",
"enum": [
false
],
"type": "string"
},
"algorithm": {
"description": "JWT signing algorithm, Supports HMAC (configured as hmac-based) and RSA, ECDSA (configured as public-key).",
"enum": [
"public-key"
],
"type": "string"
},
"public_key": {
"description": "The public key used to verify the JWT.",
"type": "string"
},
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"jwt"
],
"type": "string"
},
"acl_claim_name": {
"default": "acl",
"description": "JWT claim name to use for getting ACL rules.",
"type": "string"
},
"verify_claims": {
"default": {},
"description": "
A list of custom claims to validate, which is a list of name/value pairs.
Values can use the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
Authentication will verify that the value of claims in the JWT (taken from the Password field) matches what is required in verify_claims.
",
"items": {
"example": "any",
"type": "string"
},
"type": "array"
},
"from": {
"default": "password",
"description": "Field to take JWT from.",
"enum": [
"username",
"password"
],
"type": "string"
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
}
},
"type": "object"
},
"connector-mqtt.ingress_remote": {
"required": [
"topic"
],
"properties": {
"topic": {
"description": "Receive messages from which topic of the remote broker",
"type": "string"
},
"qos": {
"default": 1,
"description": "The QoS level to be used when subscribing to the remote broker",
"oneOf": [
{
"type": "string"
},
{
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
]
}
},
"type": "object"
},
"emqx_authz_api_sources.sources": {
"properties": {
"sources": {
"description": "Authorization sources",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_authz_api_schema.file"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.postgresql"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mysql"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.built_in_database"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_cluster"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_sentinel"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_single"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_sharded"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_rs"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_single"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.http_post"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.http_get"
}
]
},
"type": "array"
}
},
"type": "object"
},
"emqx_mgmt_api_alarms.alarm": {
"properties": {
"node": {
"description": "The name of the node that triggered this alarm.",
"example": "emqx@127.0.0.1",
"type": "string"
},
"name": {
"description": "The name of the node that triggered this alarm.",
"example": "high_system_memory_usage",
"type": "string"
},
"message": {
"description": "Alarm message, which describes the alarm content in a human-readable format.",
"example": "System memory usage is higher than 70%",
"type": "string"
},
"details": {
"description": "Alarm details, provides more alarm information, mainly for program processing.",
"example": {
"high_watermark": 70
},
"type": "object"
},
"duration": {
"description": "Indicates how long the alarm has been active in milliseconds.",
"example": 297056,
"type": "integer"
},
"activate_at": {
"description": "Alarm start time, using rfc3339 standard time format.",
"example": "2021-10-25T11:52:52.548+08:00",
"type": "string"
},
"deactivate_at": {
"description": "Alarm end time, using rfc3339 standard time format.",
"example": "2021-10-31T10:52:52.548+08:00",
"type": "string"
}
},
"type": "object"
},
"emqx_conf_schema.cluster_static": {
"properties": {
"seeds": {
"default": "",
"description": "List EMQX node names in the static cluster. See node.name.",
"items": {
"type": "string"
},
"readOnly": true,
"type": "array"
}
},
"type": "object"
},
"authn-redis.sentinel": {
"required": [
"database",
"sentinel",
"servers",
"cmd",
"backend",
"mechanism"
],
"properties": {
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"password_based"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"redis"
],
"type": "string"
},
"cmd": {
"description": "The Redis Command used to query data for authentication such as password hash, currently only supports HGET and HMGET.",
"type": "string"
},
"password_hash_algorithm": {
"default": {
"name": "sha256",
"salt_position": "prefix"
},
"description": "Options for password hash verification.",
"oneOf": [
{
"$ref": "#/components/schemas/authn-hash.other_algorithms"
},
{
"$ref": "#/components/schemas/authn-hash.pbkdf2"
},
{
"$ref": "#/components/schemas/authn-hash.bcrypt"
}
]
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
},
"servers": {
"description": "
A Node list for Cluster to connect to. The nodes should be separated with commas, such as: `Node[,Node].`
For each Node should be: The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The Redis default port 6379 is used if `[:Port]` is not specified.
",
"type": "string"
},
"redis_type": {
"default": "sentinel",
"description": "Sentinel mode. Must be set to 'sentinel' when Redis server is running in sentinel mode.",
"enum": [
"sentinel"
],
"type": "string"
},
"sentinel": {
"description": "The cluster name in Redis sentinel mode.",
"type": "string"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"database": {
"default": 0,
"description": "Redis database ID.",
"type": "integer"
},
"auto_reconnect": {
"default": true,
"deprecated": "since(\"v5.0.15\")",
"description": "Deprecated. Enable automatic reconnect to the database.",
"type": "boolean"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"broker.ssl_client_opts": {
"properties": {
"cacertfile": {
"description": "
Trusted PEM format CA certificates bundle file.
The certificates in this file are used to verify the TLS peer's certificates.
Append new certificates to the file if new CAs are to be trusted.
There is no need to restart EMQX to have the updated file loaded, because
the system regularly checks if file has been updated (and reload).
NOTE: invalidating (deleting) a certificate from the file will not affect
already established connections.
",
"type": "string"
},
"certfile": {
"description": "
PEM format certificates chain file.
The certificates in this file should be in reversed order of the certificate
issue chain. That is, the host's certificate should be placed in the beginning
of the file, followed by the immediate issuer certificate and so on.
Although the root CA certificate is optional, it should be placed at the end of
the file if it is to be added.
",
"type": "string"
},
"keyfile": {
"description": "PEM format private key file. ",
"type": "string"
},
"verify": {
"default": "verify_none",
"description": "Enable or disable peer verification. ",
"enum": [
"verify_peer",
"verify_none"
],
"type": "string"
},
"reuse_sessions": {
"default": true,
"description": "Enable TLS session reuse. ",
"type": "boolean"
},
"depth": {
"default": 10,
"description": "
Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path.
So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly;
if 1 the path can be PEER, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
",
"type": "integer"
},
"password": {
"description": "
String containing the user's password.
Only used if the private key file is password-protected.
",
"example": "",
"format": "password",
"type": "string"
},
"versions": {
"default": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
],
"description": "
All TLS/DTLS versions to be supported.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
In case PSK cipher suites are intended, make sure to configure
['tlsv1.2', 'tlsv1.1'] here.
",
"items": {
"type": "string"
},
"type": "array"
},
"ciphers": {
"default": "",
"description": "
This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\" or
[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"].
Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.
The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.
NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
PSK cipher suites: \"RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA\"
",
"items": {
"type": "string"
},
"type": "array"
},
"user_lookup_fun": {
"default": "emqx_tls_psk:lookup",
"description": "EMQX-internal callback that is used to lookup pre-shared key (PSK) identity. ",
"type": "string"
},
"secure_renegotiate": {
"default": true,
"description": "
SSL parameter renegotiation is a feature that allows a client and a server
to renegotiate the parameters of the SSL connection on the fly.
RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation,
you drop support for the insecure renegotiation, prone to MitM attacks.
",
"type": "boolean"
},
"enable": {
"default": false,
"description": "Enable TLS. ",
"type": "boolean"
},
"server_name_indication": {
"description": "
Specify the host name to be used in TLS Server Name Indication extension.
For instance, when connecting to \"server.example.net\", the genuine server
which accepts the connection and performs TLS handshake may differ from the
host the TLS client initially connects to, e.g. when connecting to an IP address
or when the host has multiple resolvable DNS records
If not specified, it will default to the host name string which is used
to establish the connection, unless it is IP addressed used.
The host name is then also used in the host name verification of the peer
certificate.
The special value 'disable' prevents the Server Name
Indication extension from being sent and disables the hostname
verification check.
",
"example": "disable",
"oneOf": [
{
"type": "string"
},
{
"enum": [
"disable"
],
"type": "string"
}
]
}
},
"type": "object"
},
"emqx_conf_schema.cluster_call": {
"properties": {
"retry_interval": {
"default": "1m",
"description": "Time interval to retry after a failed call.",
"example": "12m",
"type": "string"
},
"max_history": {
"default": 100,
"description": "Retain the maximum number of completed transactions (for queries).",
"maximum": 500,
"minimum": 1,
"type": "integer"
},
"cleanup_interval": {
"default": "5m",
"description": "Time interval to clear completed but stale transactions.
Ensure that the number of completed transactions is less than the max_history.",
"example": "12m",
"type": "string"
}
},
"type": "object"
},
"listeners.tcp_required_bind(with_name)": {
"required": [
"bind",
"name",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"tcp"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"name": {
"description": "Listener name",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"bind": {
"default": 1883,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
}
},
"type": "object"
},
"zone.overload_protection": {
"properties": {
"enable": {
"description": "React on system overload or not.",
"type": "boolean"
},
"backoff_delay": {
"description": "The maximum duration of delay for background task execution during high load conditions.",
"minimum": 0,
"type": "integer"
},
"backoff_gc": {
"description": "When at high load, skip forceful GC.",
"type": "boolean"
},
"backoff_hibernation": {
"description": "When at high load, skip process hibernation.",
"type": "boolean"
},
"backoff_new_conn": {
"description": "When at high load, close new incoming connections.",
"type": "boolean"
}
},
"type": "object"
},
"emqx_authz_api_schema.file": {
"required": [
"rules",
"type"
],
"properties": {
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "file",
"description": "Backend type.",
"enum": [
"file"
],
"type": "string"
},
"rules": {
"description": "Authorization static file rules.",
"example": "{allow,{username,\"^dashboard?\"},subscribe,[\"$SYS/#\"]}.\n{allow,{ipaddr,\"127.0.0.1\"},all,[\"$SYS/#\",\"#\"]}.",
"type": "string"
}
},
"type": "object"
},
"exhook.detail_server_info": {
"required": [
"url",
"name"
],
"properties": {
"metrics": {
"description": "Metrics information of this server in the current node",
"$ref": "#/components/schemas/exhook.metrics"
},
"node_metrics": {
"description": "Metrics information of this server in all nodes",
"items": {
"$ref": "#/components/schemas/exhook.node_metrics"
},
"type": "array"
},
"node_status": {
"description": "status of this server in all nodes",
"items": {
"$ref": "#/components/schemas/exhook.node_status"
},
"type": "array"
},
"hooks": {
"items": {
"$ref": "#/components/schemas/exhook.hook_info"
},
"type": "array"
},
"name": {
"description": "Name of the exhook server",
"example": "default",
"type": "string"
},
"enable": {
"default": true,
"description": "Enable this Exhook server",
"type": "boolean"
},
"url": {
"description": "URL of the gRPC server",
"example": "http://127.0.0.1:9000",
"type": "string"
},
"request_timeout": {
"default": "5s",
"description": "The timeout of request gRPC server",
"example": "12m",
"type": "string"
},
"failed_action": {
"default": "deny",
"description": "The value that is returned when the request to the gRPC server fails for any reason",
"enum": [
"deny",
"ignore"
],
"type": "string"
},
"ssl": {
"$ref": "#/components/schemas/exhook.ssl_conf"
},
"socket_options": {
"default": {
"keepalive": true,
"nodelay": true
},
"$ref": "#/components/schemas/exhook.socket_options"
},
"auto_reconnect": {
"default": "60s",
"description": "Whether to automatically reconnect (initialize) the gRPC server.
When gRPC is not available, Exhook tries to request the gRPC service at that interval and reinitialize the list of mounted hooks.",
"oneOf": [
{
"example": "12m",
"type": "string"
},
{
"enum": [
false
],
"type": "string"
}
]
},
"pool_size": {
"default": 8,
"description": "The process pool size for gRPC client",
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"emqx_dashboard_monitor_api.sampler": {
"properties": {
"time_stamp": {
"description": "Timestamp",
"minimum": 0,
"type": "integer"
},
"subscriptions": {
"description": "Subscriptions at the time of sampling. Can only represent the approximate state",
"type": "integer"
},
"topics": {
"description": "Count topics at the time of sampling. Can only represent the approximate state",
"type": "integer"
},
"connections": {
"description": "Connections at the time of sampling. Can only represent the approximate state",
"type": "integer"
},
"received": {
"description": "Received messages last 10 seconds",
"type": "integer"
},
"sent": {
"description": "Sent messages last 10 seconds",
"type": "integer"
},
"dropped": {
"description": "Dropped messages last 10 seconds",
"type": "integer"
}
},
"type": "object"
},
"broker.trace": {
"properties": {
"payload_encode": {
"default": "text",
"description": "
Determine the format of the payload format in the trace file.
`text`: Text-based protocol or plain text protocol.
It is recommended when payload is JSON encoded.
`hex`: Binary hexadecimal encode. It is recommended when payload is a custom binary protocol.
`hidden`: payload is obfuscated as `******`
",
"enum": [
"hex",
"text",
"hidden"
],
"type": "string"
}
},
"type": "object"
},
"emqx_rule_api_schema.ctx_check_authz_complete": {
"required": [
"event_type"
],
"properties": {
"event_type": {
"description": "Event Type",
"enum": [
"client_check_authz_complete"
],
"type": "string"
},
"clientid": {
"description": "The Client ID",
"type": "string"
},
"username": {
"description": "The User Name",
"type": "string"
},
"peerhost": {
"description": "The IP Address of the Peer Client",
"type": "string"
},
"topic": {
"description": "Message Topic",
"type": "string"
},
"action": {
"description": "Publish or Subscribe",
"type": "string"
},
"authz_source": {
"description": "Cache, Plugs or Default",
"type": "string"
},
"result": {
"description": "Allow or Deny",
"type": "string"
}
},
"type": "object"
},
"bridge_webhook.creation_opts": {
"properties": {
"worker_pool_size": {
"default": 16,
"description": "The number of buffer workers. Only applicable for egress type bridges.
For bridges only have ingress direction data flow, it can be set to 0 otherwise must be greater than 0.",
"minimum": 0,
"type": "integer"
},
"health_check_interval": {
"default": "15s",
"description": "Health check interval.",
"example": "32s",
"type": "string"
},
"start_after_created": {
"default": "true",
"description": "Whether start the resource right after created.",
"type": "boolean"
},
"start_timeout": {
"default": "5s",
"description": "Time interval to wait for an auto-started resource to become healthy before responding resource creation requests.",
"example": "32s",
"type": "string"
},
"auto_restart_interval": {
"default": "60s",
"description": "The auto restart interval after the resource is disconnected.",
"oneOf": [
{
"example": "32s",
"type": "string"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"query_mode": {
"default": "async",
"description": "Query mode. Optional 'sync/async', default 'async'.",
"enum": [
"sync",
"async"
],
"type": "string"
},
"request_timeout": {
"default": "15s",
"description": "Timeout for requests. If query_mode is sync, calls to the resource will be blocked for this amount of time before timing out.",
"oneOf": [
{
"example": "32s",
"type": "string"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"async_inflight_window": {
"default": 100,
"description": "Async query inflight window.",
"minimum": 1,
"type": "integer"
},
"enable_queue": {
"default": false,
"deprecated": "since(\"v5.0.14\")",
"description": "Enable disk buffer queue (only applicable for egress bridges).
When Enabled, messages will be buffered on disk when the bridge connection is down.
When disabled the messages are buffered in RAM only.",
"type": "boolean"
},
"max_queue_bytes": {
"default": "100MB",
"description": "Maximum number of bytes to buffer for each buffer worker.",
"example": "32MB",
"type": "string"
}
},
"type": "object"
},
"limiter.listener_client_fields": {
"properties": {
"bytes_in": {
"description": "The bytes_in limiter.
This is used to limit the inbound bytes rate for this EMQX node.
Once the limit is reached, the restricted client will be slow down even be hung for a while.",
"$ref": "#/components/schemas/limiter.client_opts"
},
"message_in": {
"description": "The message in limiter.
This is used to limit the inbound message numbers for this EMQX node
Once the limit is reached, the restricted client will be slow down even be hung for a while.",
"$ref": "#/components/schemas/limiter.client_opts"
},
"connection": {
"description": "The connection limiter.
This is used to limit the connection rate for this EMQX node.
Once the limit is reached, new connections will be refused",
"$ref": "#/components/schemas/limiter.client_opts"
},
"message_routing": {
"description": "The message routing limiter.
This is used to limit the forwarding rate for this EMQX node.
Once the limit is reached, new publish will be refused",
"$ref": "#/components/schemas/limiter.client_opts"
}
},
"type": "object"
},
"authz.metrics_status_fields": {
"properties": {
"resource_metrics": {
"description": "The metrics of the resource.",
"$ref": "#/components/schemas/authz.resource_metrics"
},
"node_resource_metrics": {
"description": "The metrics of the resource for each node.",
"items": {
"$ref": "#/components/schemas/authz.node_resource_metrics"
},
"type": "array"
},
"metrics": {
"description": "The metrics of the resource.",
"$ref": "#/components/schemas/authz.metrics"
},
"node_metrics": {
"description": "The metrics of the resource for each node.",
"items": {
"$ref": "#/components/schemas/authz.node_metrics"
},
"type": "array"
},
"status": {
"description": "The status of the resource.",
"enum": [
"connected",
"disconnected",
"connecting",
"inconsistent"
],
"type": "string"
},
"node_status": {
"description": "The status of the resource for each node.",
"items": {
"$ref": "#/components/schemas/authz.node_status"
},
"type": "array"
},
"node_error": {
"description": "The error of node.",
"items": {
"$ref": "#/components/schemas/authz.node_error"
},
"type": "array"
}
},
"type": "object"
},
"authn-hash.other_algorithms": {
"required": [
"name"
],
"properties": {
"name": {
"description": "Simple password hashing algorithm.",
"enum": [
"plain",
"md5",
"sha",
"sha256",
"sha512"
],
"type": "string"
},
"salt_position": {
"default": "prefix",
"description": "Salt position for PLAIN, MD5, SHA, SHA256 and SHA512 algorithms.",
"enum": [
"disable",
"prefix",
"suffix"
],
"type": "string"
}
},
"type": "object"
},
"emqx_authn_api.response_user": {
"required": [
"user_id"
],
"properties": {
"user_id": {
"type": "string"
},
"is_superuser": {
"default": false,
"type": "boolean"
}
},
"type": "object"
},
"broker.sysmon_vm": {
"properties": {
"process_check_interval": {
"default": "30s",
"description": "The time interval for the periodic process limit check.",
"example": "12m",
"type": "string"
},
"process_high_watermark": {
"default": "80%",
"description": "The threshold, as percentage of processes, for how many
processes can simultaneously exist at the local node before the corresponding
alarm is raised.",
"example": "12%",
"type": "number"
},
"process_low_watermark": {
"default": "60%",
"description": "The threshold, as percentage of processes, for how many
processes can simultaneously exist at the local node before the corresponding
alarm is cleared.",
"example": "12%",
"type": "number"
},
"long_gc": {
"default": "disabled",
"description": "When an Erlang process spends long time to perform garbage collection, a warning level long_gc log is emitted,
and an MQTT message is published to the system topic $SYS/sysmon/long_gc.
",
"oneOf": [
{
"example": "12m",
"type": "string"
},
{
"enum": [
"disabled"
],
"type": "string"
}
]
},
"long_schedule": {
"default": "240ms",
"description": "When the Erlang VM detect a task scheduled for too long, a warning level 'long_schedule' log is emitted,
and an MQTT message is published to the system topic $SYS/sysmon/long_schedule.
",
"oneOf": [
{
"example": "12m",
"type": "string"
},
{
"enum": [
"disabled"
],
"type": "string"
}
]
},
"large_heap": {
"default": "32MB",
"description": "When an Erlang process consumed a large amount of memory for its heap space,
the system will write a warning level large_heap log, and an MQTT message is published to
the system topic $SYS/sysmon/large_heap.
",
"oneOf": [
{
"example": "32MB",
"type": "string"
},
{
"enum": [
"disabled"
],
"type": "string"
}
]
},
"busy_dist_port": {
"default": true,
"description": "When the RPC connection used to communicate with other nodes in the cluster is overloaded,
there will be a busy_dist_port warning log,
and an MQTT message is published to system topic $SYS/sysmon/busy_dist_port.
",
"type": "boolean"
},
"busy_port": {
"default": true,
"description": "When a port (e.g. TCP socket) is overloaded, there will be a busy_port warning log,
and an MQTT message is published to the system topic $SYS/sysmon/busy_port.
",
"type": "boolean"
}
},
"type": "object"
},
"exhook.metrics": {
"properties": {
"succeed": {
"description": "The number of times the hooks execution successful",
"type": "integer"
},
"failed": {
"description": "The number of times the hook execution failed",
"type": "integer"
},
"rate": {
"description": "The call rate of hooks",
"type": "integer"
},
"max_rate": {
"description": "Maximum call rate of hooks",
"type": "integer"
}
},
"type": "object"
},
"emqx_rule_api_schema.ctx_disconnected": {
"required": [
"event_type"
],
"properties": {
"event_type": {
"description": "Event Type",
"enum": [
"client_disconnected"
],
"type": "string"
},
"clientid": {
"description": "The Client ID",
"type": "string"
},
"username": {
"description": "The User Name",
"type": "string"
},
"reason": {
"description": "The Reason for Disconnect",
"type": "string"
},
"peername": {
"description": "The IP Address and Port of the Peer Client",
"type": "string"
},
"sockname": {
"description": "The IP Address and Port of the Local Listener",
"type": "string"
},
"disconnected_at": {
"description": "The Time that this Client is Disconnected",
"type": "integer"
}
},
"type": "object"
},
"dashboard.listeners": {
"properties": {
"http": {
"description": "TCP listeners",
"$ref": "#/components/schemas/dashboard.http"
},
"https": {
"description": "SSL listeners",
"$ref": "#/components/schemas/dashboard.https"
}
},
"type": "object"
},
"listeners.tcp_required_bind": {
"required": [
"bind",
"id",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"tcp"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"id": {
"description": "Listener id",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"bind": {
"default": 1883,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
}
},
"type": "object"
},
"broker.alarm": {
"properties": {
"actions": {
"default": [
"log",
"publish"
],
"description": "The actions triggered when the alarm is activated.
Currently, the following actions are supported: log and publish.
log is to write the alarm to log (console or file).
publish is to publish the alarm as an MQTT message to the system topics:
$SYS/brokers/emqx@xx.xx.xx.x/alarms/activate and
$SYS/brokers/emqx@xx.xx.xx.x/alarms/deactivate",
"example": [
"log",
"publish"
],
"items": {
"type": "string"
},
"type": "array"
},
"size_limit": {
"default": 1000,
"description": "The maximum total number of deactivated alarms to keep as history.
When this limit is exceeded, the oldest deactivated alarms are deleted to cap the total number.
",
"example": 1000,
"maximum": 3000,
"minimum": 1,
"type": "integer"
},
"validity_period": {
"default": "24h",
"description": "Retention time of deactivated alarms. Alarms are not deleted immediately
when deactivated, but after the retention time.
",
"example": "24h",
"type": "string"
}
},
"type": "object"
},
"emqx_authz_api_schema.mongo_rs": {
"required": [
"database",
"replica_set_name",
"servers",
"collection",
"type"
],
"properties": {
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "mongodb",
"description": "Backend type.",
"enum": [
"mongodb"
],
"type": "string"
},
"collection": {
"description": "`MongoDB` collection containing the authorization data.",
"type": "string"
},
"filter": {
"default": {},
"description": "
Conditional expression that defines the filter condition in the query.
Filter supports the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
",
"example": {},
"type": "object"
},
"mongo_type": {
"default": "rs",
"description": "Replica set. Must be set to 'rs' when MongoDB server is running in 'replica set' mode.",
"enum": [
"rs"
],
"type": "string"
},
"servers": {
"description": "
A Node list for Cluster to connect to. The nodes should be separated with commas, such as: `Node[,Node].`
For each Node should be: The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The MongoDB default port 27017 is used if `[:Port]` is not specified.
",
"type": "string"
},
"w_mode": {
"default": "unsafe",
"description": "Write mode.",
"enum": [
"unsafe",
"safe"
],
"type": "string"
},
"r_mode": {
"default": "master",
"description": "Read mode.",
"enum": [
"master",
"slave_ok"
],
"type": "string"
},
"replica_set_name": {
"description": "Name of the replica set.",
"type": "string"
},
"srv_record": {
"default": false,
"description": "Use DNS SRV record.",
"type": "boolean"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"username": {
"description": "EMQX's username in the external database.",
"type": "string"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auth_source": {
"description": "Database name associated with the user's credentials.",
"type": "string"
},
"database": {
"description": "Database name.",
"type": "string"
},
"topology": {
"$ref": "#/components/schemas/emqx_connector_mongo.topology"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"gateway.exproto_grpc_handler": {
"required": [
"address"
],
"properties": {
"address": {
"description": "gRPC server address.",
"type": "string"
},
"ssl_options": {
"description": "SSL configuration for the gRPC client.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"broker.persistent_session_store": {
"properties": {
"enabled": {
"default": false,
"description": "Use the database to store information about persistent sessions.
This makes it possible to migrate a client connection to another
cluster node if a node is stopped.
",
"type": "boolean"
},
"on_disc": {
"default": true,
"description": "Save information about the persistent sessions on disc.
If this option is enabled, persistent sessions will survive full restart of the cluster.
Otherwise, all the data will be stored in RAM, and it will be lost when all the nodes in the cluster are stopped.",
"type": "boolean"
},
"ram_cache": {
"default": false,
"description": "Maintain a copy of the data in RAM for faster access.",
"type": "boolean"
},
"backend": {
"default": {
"messages": {
"ram_cache": "false"
},
"session": {
"ram_cache": "true"
},
"session_messages": {
"ram_cache": "true"
},
"type": "builtin"
},
"description": "Database management system used to store information about persistent sessions and messages.
- `builtin`: Use the embedded database (mria)",
"oneOf": [
{
"$ref": "#/components/schemas/broker.persistent_session_builtin"
}
]
},
"max_retain_undelivered": {
"default": "1h",
"description": "The time messages that was not delivered to a persistent session
is stored before being garbage collected if the node the previous
session was handled on restarts of is stopped.
",
"example": "12m",
"type": "string"
},
"message_gc_interval": {
"default": "1h",
"description": "The starting interval for garbage collection of undelivered messages to
a persistent session. This affects how often the \"max_retain_undelivered\"
is checked for removal.
",
"example": "12m",
"type": "string"
},
"session_message_gc_interval": {
"default": "1m",
"description": "The starting interval for garbage collection of transient data for
persistent session messages. This does not affect the lifetime length
of persistent session messages.
",
"example": "12m",
"type": "string"
}
},
"type": "object"
},
"authn-http.get": {
"required": [
"url",
"backend",
"mechanism",
"method"
],
"properties": {
"method": {
"default": "get",
"description": "HTTP request method.",
"enum": [
"get"
],
"type": "string"
},
"headers": {
"default": {
"accept": "application/json",
"cache-control": "no-cache",
"connection": "keep-alive",
"keep-alive": "timeout=30, max=1000"
},
"description": "List of HTTP headers (without content-type).",
"example": {},
"type": "object"
},
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"password_based"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"http"
],
"type": "string"
},
"url": {
"description": "URL of the HTTP server.",
"type": "string"
},
"body": {
"description": "HTTP request body.",
"example": {},
"type": "object"
},
"request_timeout": {
"default": "5s",
"description": "HTTP request timeout.",
"example": "32s",
"type": "string"
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
},
"connect_timeout": {
"default": "15s",
"description": "The timeout when connecting to the HTTP server.",
"example": "32s",
"type": "string"
},
"enable_pipelining": {
"default": 100,
"description": "A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.",
"minimum": 1,
"type": "integer"
},
"max_retries": {
"deprecated": "since(\"5.0.4\")",
"minimum": 0,
"type": "integer"
},
"pool_size": {
"default": 8,
"description": "The pool size.",
"minimum": 1,
"type": "integer"
},
"request": {
"description": "Configure HTTP request parameters.",
"$ref": "#/components/schemas/connector-http.request"
},
"retry_interval": {
"deprecated": "since(\"5.0.4\")",
"example": "12m",
"type": "string"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"broker.broker": {
"properties": {
"enable_session_registry": {
"default": true,
"description": "Enable session registry",
"type": "boolean"
},
"session_locking_strategy": {
"default": "quorum",
"description": "Session locking strategy in a cluster.
- `local`: only lock the session on the current node
- `one`: select only one remote node to lock the session
- `quorum`: select some nodes to lock the session
- `all`: lock the session on all the nodes in the cluster
",
"enum": [
"local",
"leader",
"quorum",
"all"
],
"type": "string"
},
"shared_subscription_strategy": {
"default": "round_robin",
"description": "Dispatch strategy for shared subscription.
- `random`: dispatch the message to a random selected subscriber
- `round_robin`: select the subscribers in a round-robin manner
- `sticky`: always use the last selected subscriber to dispatch, until the subscriber disconnects.
- `hash`: select the subscribers by the hash of `clientIds`
",
"enum": [
"random",
"round_robin",
"round_robin_per_group",
"sticky",
"local",
"hash_topic",
"hash_clientid"
],
"type": "string"
},
"shared_dispatch_ack_enabled": {
"default": false,
"description": "Deprecated, will be removed in 5.1.
Enable/disable shared dispatch acknowledgement for QoS 1 and QoS 2 messages.
This should allow messages to be dispatched to a different subscriber in the group in case the picked (based on `shared_subscription_strategy`) subscriber is offline.
",
"type": "boolean"
},
"route_batch_clean": {
"default": true,
"description": "Enable batch clean for deleted routes.",
"type": "boolean"
},
"perf": {
"$ref": "#/components/schemas/broker.broker_perf"
},
"shared_subscription_group": {
"description": "Per group dispatch strategy for shared subscription.
This config is a map from shared subscription group name to the strategy
name. The group name should be of format `[A-Za-z0-9]`. i.e. no
special characters are allowed.
",
"example": {
"example_group": {
"strategy": "random"
}
},
"properties": {
"$name": {
"$ref": "#/components/schemas/broker.shared_subscription_group"
}
},
"type": "object"
}
},
"type": "object"
},
"emqx_mgmt_api_publish.bad_request": {
"properties": {
"code": {
"description": "BAD_REQUEST",
"type": "string"
},
"message": {
"description": "Describes the failure reason in detail.",
"type": "string"
}
},
"type": "object"
},
"authn-postgresql.authentication": {
"required": [
"database",
"server",
"query",
"backend",
"mechanism"
],
"properties": {
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"password_based"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"postgresql"
],
"type": "string"
},
"password_hash_algorithm": {
"default": {
"name": "sha256",
"salt_position": "prefix"
},
"description": "Options for password hash verification.",
"oneOf": [
{
"$ref": "#/components/schemas/authn-hash.other_algorithms"
},
{
"$ref": "#/components/schemas/authn-hash.pbkdf2"
},
{
"$ref": "#/components/schemas/authn-hash.bcrypt"
}
]
},
"query": {
"description": "SQL used to query data for authentication, such as password hash.",
"type": "string"
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
},
"server": {
"description": "
The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The PostgreSQL default port 5432 is used if `[:Port]` is not specified.
",
"type": "string"
},
"database": {
"description": "Database name.",
"type": "string"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"username": {
"description": "EMQX's username in the external database.",
"type": "string"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auto_reconnect": {
"default": true,
"deprecated": "since(\"v5.0.15\")",
"description": "Deprecated. Enable automatic reconnect to the database.",
"type": "boolean"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"emqx_authn_schema.resource_metrics": {
"properties": {
"matched": {
"description": "Count of this resource is queried.",
"type": "integer"
},
"success": {
"description": "Count of query success.",
"type": "integer"
},
"failed": {
"description": "Count of query failed.",
"type": "integer"
},
"rate": {
"description": "The rate of matched, times/second.",
"type": "number"
},
"rate_max": {
"description": "The max rate of matched, times/second.",
"type": "number"
},
"rate_last5m": {
"description": "The average rate of matched in the last 5 minutes, times/second.",
"type": "number"
}
},
"type": "object"
},
"exhook.list_hook_info": {
"properties": {
"name": {
"description": "The hook's name",
"type": "string"
},
"params": {
"description": "The parameters used when the hook is registered",
"properties": {
"$name": {
"type": "string"
}
},
"type": "object"
},
"metrics": {
"description": "Metrics information of this hook in the current node",
"$ref": "#/components/schemas/exhook.metrics"
},
"node_metrics": {
"description": "Metrics information of this hook in all nodes",
"items": {
"$ref": "#/components/schemas/exhook.node_metrics"
},
"type": "array"
}
},
"type": "object"
},
"emqx_gateway_api_listeners.udp_listener": {
"properties": {
"id": {
"description": "Listener ID",
"type": "string"
},
"type": {
"description": "Listener Type",
"enum": [
"udp"
],
"type": "string"
},
"name": {
"description": "Listener Name",
"type": "string"
},
"running": {
"description": "Listener Running status",
"type": "boolean"
},
"udp_options": {
"$ref": "#/components/schemas/gateway.udp_opts"
},
"enable": {
"default": true,
"description": "Enable the listener.",
"type": "boolean"
},
"bind": {
"description": "The IP address and port that the listener will bind.",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"max_connections": {
"default": 1024,
"description": "Maximum number of concurrent connections.",
"type": "integer"
},
"max_conn_rate": {
"default": 1000,
"description": "Maximum connections per second.",
"type": "integer"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"enable_authn": {
"default": true,
"description": "Set true (default) to enable client authentication on this listener.
When set to false clients will be allowed to connect without authentication.",
"type": "boolean"
},
"mountpoint": {
"description": "When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint` set to `some_tenant`, then the client actually subscribes to the topic `some_tenant/t`. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic `t`, the message is routed to all the clients subscribed `some_tenant/t`, so client A will receive the message, with topic name `t`. Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"access_rules": {
"default": "",
"description": "The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny",
"items": {
"type": "string"
},
"type": "array"
},
"status": {
"description": "listener status ",
"$ref": "#/components/schemas/listeners.status"
},
"node_status": {
"description": "listener status of each node in the cluster",
"items": {
"$ref": "#/components/schemas/listeners.node_status"
},
"type": "array"
}
},
"type": "object"
},
"emqx_authz_api_mnesia.rule_item": {
"required": [
"action",
"permission",
"topic"
],
"properties": {
"topic": {
"description": "Rule on specific topic",
"example": "test/topic/1",
"type": "string"
},
"permission": {
"description": "Permission",
"enum": [
"allow",
"deny"
],
"example": "allow",
"type": "string"
},
"action": {
"description": "Authorized action (pub/sub/all)",
"enum": [
"publish",
"subscribe",
"all"
],
"example": "publish",
"type": "string"
}
},
"type": "object"
},
"authn-jwt.jwks": {
"required": [
"mechanism",
"endpoint",
"use_jwks"
],
"properties": {
"use_jwks": {
"description": "Whether to use JWKS.",
"enum": [
true
],
"type": "string"
},
"endpoint": {
"description": "JWKS endpoint, it's a read-only endpoint that returns the server's public key set in the JWKS format.",
"type": "string"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"refresh_interval": {
"default": 300,
"description": "JWKS refresh interval.",
"type": "integer"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL options.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
},
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"jwt"
],
"type": "string"
},
"acl_claim_name": {
"default": "acl",
"description": "JWT claim name to use for getting ACL rules.",
"type": "string"
},
"verify_claims": {
"default": {},
"description": "
A list of custom claims to validate, which is a list of name/value pairs.
Values can use the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
Authentication will verify that the value of claims in the JWT (taken from the Password field) matches what is required in verify_claims.
",
"items": {
"example": "any",
"type": "string"
},
"type": "array"
},
"from": {
"default": "password",
"description": "Field to take JWT from.",
"enum": [
"username",
"password"
],
"type": "string"
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
}
},
"type": "object"
},
"trace.trace": {
"required": [
"type",
"name"
],
"properties": {
"name": {
"description": "Unique and format by [a-zA-Z0-9-_]",
"example": "EMQX-TRACE-1",
"type": "string"
},
"type": {
"description": "Filter type",
"enum": [
"clientid",
"topic",
"ip_address"
],
"example": "clientid",
"type": "string"
},
"topic": {
"description": "support mqtt wildcard topic.",
"example": "/dev/#",
"type": "string"
},
"clientid": {
"description": "mqtt clientid.",
"example": "dev-001",
"type": "string"
},
"ip_address": {
"description": "client ip address",
"example": "127.0.0.1",
"type": "string"
},
"status": {
"description": "trace status",
"enum": [
"running",
"stopped",
"waiting"
],
"example": "running",
"type": "string"
},
"start_at": {
"description": "rfc3339 timestamp or epoch second",
"example": "2021-11-04T18:17:38+08:00",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"end_at": {
"description": "rfc3339 timestamp or epoch second",
"example": "2021-11-05T18:17:38+08:00",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"log_size": {
"description": "trace log size",
"example": [
{
"node": "emqx@127.0.0.1",
"size": 1024
}
],
"items": {
"example": {},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"gateway.udp_opts": {
"properties": {
"active_n": {
"default": 100,
"description": "Specify the {active, N} option for the socket.
See: https://erlang.org/doc/man/inet.html#setopts-2",
"type": "integer"
},
"recbuf": {
"description": "Size of the kernel-space receive buffer for the socket.",
"example": "32MB",
"type": "string"
},
"sndbuf": {
"description": "Size of the kernel-space send buffer for the socket.",
"example": "32MB",
"type": "string"
},
"buffer": {
"description": "Size of the user-space buffer for the socket.",
"example": "32MB",
"type": "string"
},
"reuseaddr": {
"default": true,
"description": "Allow local reuse of port numbers.",
"type": "boolean"
}
},
"type": "object"
},
"emqx_gateway_api.coap": {
"properties": {
"name": {
"description": "Gateway Name",
"enum": [
"coap"
],
"type": "string"
},
"heartbeat": {
"default": "30s",
"description": "The gateway server required minimum heartbeat interval.
When connection mode is enabled, this parameter is used to set the minimum heartbeat interval for the connection to be alive",
"example": "12m",
"type": "string"
},
"connection_required": {
"default": false,
"description": "Enable or disable connection mode.
Connection mode is a feature of non-standard protocols. When connection mode is enabled, it is necessary to maintain the creation, authentication and alive of connection resources",
"type": "boolean"
},
"notify_type": {
"default": "qos",
"description": "The Notification Message will be delivered to the CoAP client if a new message received on an observed topic.
The type of delivered coap message can be set to:
- non: Non-confirmable;
- con: Confirmable;
- qos: Mapping from QoS type of received message, QoS0 -> non, QoS1,2 -> con
",
"enum": [
"non",
"con",
"qos"
],
"type": "string"
},
"subscribe_qos": {
"default": "coap",
"description": "The Default QoS Level indicator for subscribe request.
This option specifies the QoS level for the CoAP Client when establishing a subscription membership, if the subscribe request is not carried `qos` option. The indicator can be set to:
- qos0, qos1, qos2: Fixed default QoS level
- coap: Dynamic QoS level by the message type of subscribe request
* qos0: If the subscribe request is non-confirmable
* qos1: If the subscribe request is confirmable
",
"enum": [
"qos0",
"qos1",
"qos2",
"coap"
],
"type": "string"
},
"publish_qos": {
"default": "coap",
"description": "The Default QoS Level indicator for publish request.
This option specifies the QoS level for the CoAP Client when publishing a message to EMQX PUB/SUB system, if the publish request is not carried `qos` option. The indicator can be set to:
- qos0, qos1, qos2: Fixed default QoS level
- coap: Dynamic QoS level by the message type of publish request
* qos0: If the publish request is non-confirmable
* qos1: If the publish request is confirmable",
"enum": [
"qos0",
"qos1",
"qos2",
"coap"
],
"type": "string"
},
"mountpoint": {
"default": "",
"description": " ",
"type": "string"
},
"enable": {
"default": true,
"description": "Whether to enable this gateway",
"type": "boolean"
},
"enable_stats": {
"default": true,
"description": "Whether to enable client process statistic",
"type": "boolean"
},
"idle_timeout": {
"default": "30s",
"description": "The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.",
"example": "12m",
"type": "string"
},
"clientinfo_override": {
"description": "ClientInfo override.",
"$ref": "#/components/schemas/gateway.clientinfo_override"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"listeners": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.dtls_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.udp_listener"
}
]
},
"type": "array"
}
},
"type": "object"
},
"emqx_authn_schema.node_error": {
"properties": {
"node": {
"description": "Node name.",
"example": "emqx@127.0.0.1",
"type": "string"
},
"error": {
"description": "The error of node.",
"type": "string"
}
},
"type": "object"
},
"authn-mongodb.standalone": {
"required": [
"database",
"server",
"collection",
"backend",
"mechanism"
],
"properties": {
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"password_based"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"mongodb"
],
"type": "string"
},
"collection": {
"description": "Collection used to store authentication data.",
"type": "string"
},
"filter": {
"default": {},
"description": "
Conditional expression that defines the filter condition in the query.
Filter supports the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
",
"example": {},
"type": "object"
},
"password_hash_field": {
"default": "password_hash",
"description": "Document field that contains password hash.",
"type": "string"
},
"salt_field": {
"default": "salt",
"description": "Document field that contains the password salt.",
"type": "string"
},
"is_superuser_field": {
"default": "is_superuser",
"description": "Document field that defines if the user has superuser privileges.",
"type": "string"
},
"password_hash_algorithm": {
"default": {
"name": "sha256",
"salt_position": "prefix"
},
"description": "Options for password hash verification.",
"oneOf": [
{
"$ref": "#/components/schemas/authn-hash.other_algorithms"
},
{
"$ref": "#/components/schemas/authn-hash.pbkdf2"
},
{
"$ref": "#/components/schemas/authn-hash.bcrypt"
}
]
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
},
"mongo_type": {
"default": "single",
"description": "Standalone instance. Must be set to 'single' when MongoDB server is running in standalone mode.",
"enum": [
"single"
],
"type": "string"
},
"server": {
"description": "
The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The MongoDB default port 27017 is used if `[:Port]` is not specified.
",
"type": "string"
},
"w_mode": {
"default": "unsafe",
"description": "Write mode.",
"enum": [
"unsafe",
"safe"
],
"type": "string"
},
"srv_record": {
"default": false,
"description": "Use DNS SRV record.",
"type": "boolean"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"username": {
"description": "EMQX's username in the external database.",
"type": "string"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auth_source": {
"description": "Database name associated with the user's credentials.",
"type": "string"
},
"database": {
"description": "Database name.",
"type": "string"
},
"topology": {
"$ref": "#/components/schemas/emqx_connector_mongo.topology"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"emqx_gateway_api_listeners.dtls_listener": {
"properties": {
"id": {
"description": "Listener ID",
"type": "string"
},
"type": {
"description": "Listener Type",
"enum": [
"dtls"
],
"type": "string"
},
"name": {
"description": "Listener Name",
"type": "string"
},
"running": {
"description": "Listener Running status",
"type": "boolean"
},
"acceptors": {
"default": 16,
"description": "Size of the acceptor pool.",
"type": "integer"
},
"udp_options": {
"$ref": "#/components/schemas/gateway.udp_opts"
},
"enable": {
"default": true,
"description": "Enable the listener.",
"type": "boolean"
},
"bind": {
"description": "The IP address and port that the listener will bind.",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"max_connections": {
"default": 1024,
"description": "Maximum number of concurrent connections.",
"type": "integer"
},
"max_conn_rate": {
"default": 1000,
"description": "Maximum connections per second.",
"type": "integer"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"enable_authn": {
"default": true,
"description": "Set true (default) to enable client authentication on this listener.
When set to false clients will be allowed to connect without authentication.",
"type": "boolean"
},
"mountpoint": {
"description": "When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint` set to `some_tenant`, then the client actually subscribes to the topic `some_tenant/t`. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic `t`, the message is routed to all the clients subscribed `some_tenant/t`, so client A will receive the message, with topic name `t`. Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"access_rules": {
"default": "",
"description": "The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny",
"items": {
"type": "string"
},
"type": "array"
},
"dtls_options": {
"description": "DTLS socket options",
"$ref": "#/components/schemas/gateway.dtls_opts"
},
"status": {
"description": "listener status ",
"$ref": "#/components/schemas/listeners.status"
},
"node_status": {
"description": "listener status of each node in the cluster",
"items": {
"$ref": "#/components/schemas/listeners.node_status"
},
"type": "array"
}
},
"type": "object"
},
"emqx_rule_api_schema.ctx_connack": {
"required": [
"event_type"
],
"properties": {
"event_type": {
"description": "Event Type",
"enum": [
"client_connack"
],
"type": "string"
},
"reason_code": {
"description": "The reason code",
"type": "string"
},
"clientid": {
"description": "The Client ID",
"type": "string"
},
"clean_start": {
"default": true,
"description": "Clean Start",
"type": "boolean"
},
"username": {
"description": "The User Name",
"type": "string"
},
"peername": {
"description": "The IP Address and Port of the Peer Client",
"type": "string"
},
"sockname": {
"description": "The IP Address and Port of the Local Listener",
"type": "string"
},
"proto_name": {
"description": "Protocol Name",
"type": "string"
},
"proto_ver": {
"description": "Protocol Version",
"type": "string"
},
"keepalive": {
"description": "KeepAlive",
"type": "integer"
},
"expiry_interval": {
"description": "Expiry Interval",
"type": "integer"
},
"connected_at": {
"description": "The Time that this Client is Connected",
"type": "integer"
}
},
"type": "object"
},
"emqx_authz_api_schema.redis_single": {
"required": [
"database",
"server",
"cmd",
"type"
],
"properties": {
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "redis",
"description": "Backend type.",
"enum": [
"redis"
],
"type": "string"
},
"cmd": {
"description": "Database query used to retrieve authorization data.",
"example": "HGETALL mqtt_authz",
"type": "string"
},
"server": {
"description": "
The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The Redis default port 6379 is used if `[:Port]` is not specified.
",
"type": "string"
},
"redis_type": {
"default": "single",
"description": "Single mode. Must be set to 'single' when Redis server is running in single mode.",
"enum": [
"single"
],
"type": "string"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"database": {
"default": 0,
"description": "Redis database ID.",
"type": "integer"
},
"auto_reconnect": {
"default": true,
"deprecated": "since(\"v5.0.15\")",
"description": "Deprecated. Enable automatic reconnect to the database.",
"type": "boolean"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"prometheus.prometheus": {
"required": [
"vm_msacc_collector",
"vm_memory_collector",
"vm_system_info_collector",
"vm_statistics_collector",
"mnesia_collector",
"vm_dist_collector",
"enable",
"job_name",
"interval",
"push_gateway_server"
],
"properties": {
"push_gateway_server": {
"default": "http://127.0.0.1:9091",
"description": "URL of Prometheus server",
"type": "string"
},
"interval": {
"default": "15s",
"description": "Data reporting interval",
"example": "32s",
"type": "string"
},
"headers": {
"default": {},
"description": "A list of HTTP Headers when pushing to Push Gateway.
For example, { Authorization = \"some-authz-tokens\"}",
"items": {
"example": {},
"type": "object"
},
"type": "array"
},
"job_name": {
"default": "${name}/instance/${name}~${host}",
"description": "Job Name that is pushed to the Push Gateway. Available variables:
- ${name}: Name of EMQX node.
- ${host}: Host name of EMQX node.
For example, when the EMQX node name is emqx@127.0.0.1 then the name variable takes value emqx and the host variable takes value 127.0.0.1.
Default value is: ${name}/instance/${name}~${host}
",
"type": "string"
},
"enable": {
"default": false,
"description": "Turn Prometheus data pushing on or off",
"type": "boolean"
},
"vm_dist_collector": {
"default": "enabled",
"description": "Enable or disable VM distribution collector, collects information about the sockets and processes involved in the Erlang distribution mechanism.",
"enum": [
"enabled",
"disabled"
],
"type": "string"
},
"mnesia_collector": {
"default": "enabled",
"description": "Enable or disable Mnesia collector, collects Mnesia metrics mainly using mnesia:system_info/1 .",
"enum": [
"enabled",
"disabled"
],
"type": "string"
},
"vm_statistics_collector": {
"default": "enabled",
"description": "Enable or disable VM statistics collector, collects Erlang VM metrics using erlang:statistics/1 .",
"enum": [
"enabled",
"disabled"
],
"type": "string"
},
"vm_system_info_collector": {
"default": "enabled",
"description": "Enable or disable VM system info collector, collects Erlang VM metrics using erlang:system_info/1 .",
"enum": [
"enabled",
"disabled"
],
"type": "string"
},
"vm_memory_collector": {
"default": "enabled",
"description": "Enable or disable VM memory collector, collects information about memory dynamically allocated by the Erlang emulator using erlang:memory/0 , also provides basic (D)ETS statistics .",
"enum": [
"enabled",
"disabled"
],
"type": "string"
},
"vm_msacc_collector": {
"default": "enabled",
"description": "Enable or disable VM msacc collector, collects microstate accounting metrics using erlang:statistics(microstate_accounting) .",
"enum": [
"enabled",
"disabled"
],
"type": "string"
}
},
"type": "object"
},
"authz.metrics": {
"properties": {
"total": {
"description": "The total number of times the authorization rule was triggered.",
"type": "integer"
},
"allow": {
"description": "The number of times the authentication was successful.",
"type": "integer"
},
"deny": {
"description": "The number of authentication failures.",
"type": "integer"
},
"nomatch": {
"description": "The number of times that no authorization rules were matched.",
"type": "number"
},
"rate": {
"description": "The rate of matched, times/second.",
"type": "number"
},
"rate_max": {
"description": "The max rate of matched, times/second.",
"type": "number"
},
"rate_last5m": {
"description": "The average rate of matched in the last 5 minutes, times/second.",
"type": "number"
}
},
"type": "object"
},
"emqx_gateway_api.mqttsn": {
"required": [
"gateway_id"
],
"properties": {
"name": {
"description": "Gateway Name",
"enum": [
"mqttsn"
],
"type": "string"
},
"gateway_id": {
"default": 1,
"description": "MQTT-SN Gateway ID.
When the broadcast option is enabled, the gateway will broadcast ADVERTISE message with this value",
"type": "integer"
},
"broadcast": {
"default": false,
"description": "Whether to periodically broadcast ADVERTISE messages",
"type": "boolean"
},
"enable_qos3": {
"default": true,
"description": "Allows connectionless clients to publish messages with a Qos of -1.
This feature is defined for very simple client implementations which do not support any other features except this one. There is no connection setup nor tear down, no registration nor subscription. The client just sends its 'PUBLISH' messages to a GW",
"type": "boolean"
},
"subs_resume": {
"default": false,
"description": "Whether to initiate all subscribed topic name registration messages to the client after the Session has been taken over by a new channel",
"type": "boolean"
},
"predefined": {
"default": "",
"description": "The pre-defined topic IDs and topic names.
A 'pre-defined' topic ID is a topic ID whose mapping to a topic name is known in advance by both the client's application and the gateway",
"items": {
"$ref": "#/components/schemas/gateway.mqttsn_predefined"
},
"type": "array"
},
"mountpoint": {
"default": "",
"description": " ",
"type": "string"
},
"enable": {
"default": true,
"description": "Whether to enable this gateway",
"type": "boolean"
},
"enable_stats": {
"default": true,
"description": "Whether to enable client process statistic",
"type": "boolean"
},
"idle_timeout": {
"default": "30s",
"description": "The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.",
"example": "12m",
"type": "string"
},
"clientinfo_override": {
"description": "ClientInfo override.",
"$ref": "#/components/schemas/gateway.clientinfo_override"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"listeners": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.dtls_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.udp_listener"
}
]
},
"type": "array"
}
},
"type": "object"
},
"rule_engine.builtin_action_console": {
"properties": {
"function": {
"description": "Print the actions to the console",
"enum": [
"console"
],
"type": "string"
}
},
"type": "object"
},
"bridge_mqtt.put": {
"required": [
"server"
],
"properties": {
"enable": {
"default": true,
"description": "Enable or disable this bridge",
"type": "boolean"
},
"resource_opts": {
"default": {},
"description": "Resource options.",
"$ref": "#/components/schemas/bridge_mqtt.creation_opts"
},
"mode": {
"default": "cluster_shareload",
"description": "
The mode of the MQTT Bridge.
- cluster_shareload: create an MQTT connection on each node in the emqx cluster.
In 'cluster_shareload' mode, the incoming load from the remote broker is shared by
using shared subscription.
Note that the 'clientid' is suffixed by the node name, this is to avoid
clientid conflicts between different nodes. And we can only use shared subscription
topic filters for remote.topic of ingress connections.
",
"enum": [
"cluster_shareload"
],
"type": "string"
},
"server": {
"description": "The host and port of the remote MQTT broker",
"type": "string"
},
"clientid_prefix": {
"description": "Optional prefix to prepend to the clientid used by egress bridges.",
"type": "string"
},
"proto_ver": {
"default": "v4",
"description": "The MQTT protocol version",
"enum": [
"v3",
"v4",
"v5"
],
"type": "string"
},
"bridge_mode": {
"default": false,
"description": "
If enable bridge mode.
NOTE: This setting is only for MQTT protocol version older than 5.0, and the remote MQTT
broker MUST support this feature.
",
"type": "boolean"
},
"username": {
"description": "The username of the MQTT protocol",
"type": "string"
},
"password": {
"description": "The password of the MQTT protocol",
"format": "password",
"type": "string"
},
"clean_start": {
"default": true,
"deprecated": "since(\"v5.0.16\")",
"description": "The clean-start or the clean-session of the MQTT protocol",
"type": "boolean"
},
"keepalive": {
"default": "300s",
"description": "MQTT Keepalive. Time interval is a string that contains a number followed by time unit:
- `ms` for milliseconds,
- `s` for seconds,
- `m` for minutes,
- `h` for hours;
or combination of whereof: `1h5m0s`",
"type": "string"
},
"retry_interval": {
"default": "15s",
"description": "Message retry interval. Delay for the MQTT bridge to retry sending the QoS1/QoS2 messages in case of ACK not received. Time interval is a string that contains a number followed by time unit:
- `ms` for milliseconds,
- `s` for seconds,
- `m` for minutes,
- `h` for hours;
or combination of whereof: `1h5m0s`",
"type": "string"
},
"max_inflight": {
"default": 32,
"description": "Max inflight (sent, but un-acked) messages of the MQTT protocol",
"minimum": 0,
"type": "integer"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
},
"ingress": {
"description": "The ingress config defines how this bridge receive messages from the remote MQTT broker, and then
send them to the local broker.
Template with variables is allowed in 'remote.qos', 'local.topic', 'local.qos', 'local.retain', 'local.payload'.
NOTE: if this bridge is used as the input of a rule, and also 'local.topic' is
configured, then messages got from the remote broker will be sent to both the 'local.topic' and
the rule.",
"$ref": "#/components/schemas/connector-mqtt.ingress"
},
"egress": {
"description": "The egress config defines how this bridge forwards messages from the local broker to the remote broker.
Template with variables is allowed in 'remote.topic', 'local.qos', 'local.retain', 'local.payload'.
NOTE: if this bridge is used as the action of a rule, and also 'local.topic'
is configured, then both the data got from the rule and the MQTT messages that matches
'local.topic' will be forwarded.",
"$ref": "#/components/schemas/connector-mqtt.egress"
}
},
"type": "object"
},
"authn-hash.bcrypt": {
"required": [
"name"
],
"properties": {
"name": {
"description": "BCRYPT password hashing.",
"enum": [
"bcrypt"
],
"type": "string"
}
},
"type": "object"
},
"exhook.ssl_conf": {
"properties": {
"cacertfile": {
"description": "
Trusted PEM format CA certificates bundle file.
The certificates in this file are used to verify the TLS peer's certificates.
Append new certificates to the file if new CAs are to be trusted.
There is no need to restart EMQX to have the updated file loaded, because
the system regularly checks if file has been updated (and reload).
NOTE: invalidating (deleting) a certificate from the file will not affect
already established connections.
",
"type": "string"
},
"certfile": {
"description": "
PEM format certificates chain file.
The certificates in this file should be in reversed order of the certificate
issue chain. That is, the host's certificate should be placed in the beginning
of the file, followed by the immediate issuer certificate and so on.
Although the root CA certificate is optional, it should be placed at the end of
the file if it is to be added.
",
"type": "string"
},
"keyfile": {
"description": "PEM format private key file. ",
"type": "string"
},
"verify": {
"default": "verify_none",
"description": "Enable or disable peer verification. ",
"enum": [
"verify_peer",
"verify_none"
],
"type": "string"
},
"reuse_sessions": {
"default": true,
"description": "Enable TLS session reuse. ",
"type": "boolean"
},
"depth": {
"default": 10,
"description": "
Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path.
So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly;
if 1 the path can be PEER, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
",
"type": "integer"
},
"password": {
"description": "
String containing the user's password.
Only used if the private key file is password-protected.
",
"example": "",
"format": "password",
"type": "string"
},
"versions": {
"default": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
],
"description": "
All TLS/DTLS versions to be supported.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
In case PSK cipher suites are intended, make sure to configure
['tlsv1.2', 'tlsv1.1'] here.
",
"items": {
"type": "string"
},
"type": "array"
},
"ciphers": {
"default": "",
"description": "
This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\" or
[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"].
Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.
The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.
NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
PSK cipher suites: \"RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA\"
",
"items": {
"type": "string"
},
"type": "array"
},
"secure_renegotiate": {
"default": true,
"description": "
SSL parameter renegotiation is a feature that allows a client and a server
to renegotiate the parameters of the SSL connection on the fly.
RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation,
you drop support for the insecure renegotiation, prone to MitM attacks.
",
"type": "boolean"
},
"enable": {
"default": false,
"description": "Enable TLS. ",
"type": "boolean"
},
"server_name_indication": {
"description": "
Specify the host name to be used in TLS Server Name Indication extension.
For instance, when connecting to \"server.example.net\", the genuine server
which accepts the connection and performs TLS handshake may differ from the
host the TLS client initially connects to, e.g. when connecting to an IP address
or when the host has multiple resolvable DNS records
If not specified, it will default to the host name string which is used
to establish the connection, unless it is IP addressed used.
The host name is then also used in the host name verification of the peer
certificate.
The special value 'disable' prevents the Server Name
Indication extension from being sent and disables the hostname
verification check.
",
"example": "disable",
"oneOf": [
{
"type": "string"
},
{
"enum": [
"disable"
],
"type": "string"
}
]
}
},
"type": "object"
},
"lwm2m.resource": {
"properties": {
"operations": {
"description": "Resource Operations",
"example": "E",
"type": "string"
},
"dataType": {
"description": "Data Type",
"enum": [
"Integer",
"Float",
"Time",
"String",
"Boolean",
"Opaque",
"Objlnk"
],
"example": "Integer",
"type": "string"
},
"path": {
"description": "Resource Path",
"example": "urn:oma:lwm2m:oma:2",
"type": "string"
},
"name": {
"description": "Resource Name",
"example": "lwm2m-test",
"type": "string"
}
},
"type": "object"
},
"gateway.lwm2m_translators": {
"required": [
"update",
"register",
"notify",
"response",
"command"
],
"properties": {
"command": {
"description": "The topic for receiving downstream commands.
For each new LwM2M client that succeeds in going online, the gateway creates a subscription relationship to receive downstream commands and send it to the LwM2M client",
"$ref": "#/components/schemas/gateway.translator"
},
"response": {
"description": "The topic for gateway to publish the acknowledge events from LwM2M client",
"$ref": "#/components/schemas/gateway.translator"
},
"notify": {
"description": "The topic for gateway to publish the notify events from LwM2M client.
After succeed observe a resource of LwM2M client, Gateway will send the notify events via this topic, if the client reports any resource changes",
"$ref": "#/components/schemas/gateway.translator"
},
"register": {
"description": "The topic for gateway to publish the register events from LwM2M client.",
"$ref": "#/components/schemas/gateway.translator"
},
"update": {
"description": "The topic for gateway to publish the update events from LwM2M client",
"$ref": "#/components/schemas/gateway.translator"
}
},
"type": "object"
},
"listeners.ssl_required_bind": {
"required": [
"bind",
"id",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"ssl"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"id": {
"description": "Listener id",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"bind": {
"default": 8883,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
},
"access_rules": {
"default": [
"allow all"
],
"description": "
The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny
",
"items": {
"type": "string"
},
"type": "array"
},
"proxy_protocol": {
"default": false,
"description": "
Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/
",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "3s",
"description": "
Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.
",
"example": "12m",
"type": "string"
},
"tcp_options": {
"$ref": "#/components/schemas/broker.tcp_opts"
},
"ssl_options": {
"$ref": "#/components/schemas/broker.listener_ssl_opts"
}
},
"type": "object"
},
"gateway.stomp_frame": {
"properties": {
"max_headers": {
"default": 10,
"description": "The maximum number of Header",
"minimum": 0,
"type": "integer"
},
"max_headers_length": {
"default": 1024,
"description": "The maximum string length of the Header Value",
"minimum": 0,
"type": "integer"
},
"max_body_length": {
"default": 65536,
"description": "Maximum number of bytes of Body allowed per Stomp packet",
"type": "integer"
}
},
"type": "object"
},
"retainer.message_summary": {
"properties": {
"msgid": {
"description": "Message ID.",
"type": "string"
},
"topic": {
"description": "Topic.",
"type": "string"
},
"qos": {
"description": "QoS.",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
},
"publish_at": {
"description": "Message publish time, RFC 3339 format.",
"type": "string"
},
"from_clientid": {
"description": "The clientid of publisher.",
"type": "string"
},
"from_username": {
"description": "The username of publisher.",
"type": "string"
}
},
"type": "object"
},
"broker.broker_perf": {
"properties": {
"route_lock_type": {
"default": "key",
"description": "Performance tuning for subscribing/unsubscribing a wildcard topic.
Change this parameter only when there are many wildcard topics.
NOTE: when changing from/to `global` lock, it requires all nodes in the cluster to be stopped before the change.
- `key`: mnesia transactional updates with per-key locks. Recommended for a single-node setup.
- `tab`: mnesia transactional updates with table lock. Recommended for a cluster setup.
- `global`: updates are protected with a global lock. Recommended for large clusters.
",
"enum": [
"key",
"tab",
"global"
],
"type": "string"
},
"trie_compaction": {
"default": true,
"description": "Enable trie path compaction.
Enabling it significantly improves wildcard topic subscribe rate, if wildcard topics have unique prefixes like: 'sensor/{{id}}/+/', where ID is unique per subscriber.
Topic match performance (when publishing) may degrade if messages are mostly published to topics with large number of levels.
NOTE: This is a cluster-wide configuration. It requires all nodes to be stopped before changing it.
",
"type": "boolean"
}
},
"type": "object"
},
"emqx_mgmt_api_topics.topic": {
"required": [
"node",
"topic"
],
"properties": {
"topic": {
"description": "Topic Name",
"type": "string"
},
"node": {
"description": "Node",
"type": "string"
}
},
"type": "object"
},
"emqx_rule_api_schema.ctx_connected": {
"required": [
"event_type"
],
"properties": {
"event_type": {
"description": "Event Type",
"enum": [
"client_connected"
],
"type": "string"
},
"clientid": {
"description": "The Client ID",
"type": "string"
},
"username": {
"description": "The User Name",
"type": "string"
},
"mountpoint": {
"description": "The Mountpoint",
"type": "string"
},
"peername": {
"description": "The IP Address and Port of the Peer Client",
"type": "string"
},
"sockname": {
"description": "The IP Address and Port of the Local Listener",
"type": "string"
},
"proto_name": {
"description": "Protocol Name",
"type": "string"
},
"proto_ver": {
"description": "Protocol Version",
"type": "string"
},
"keepalive": {
"description": "KeepAlive",
"type": "integer"
},
"clean_start": {
"default": true,
"description": "Clean Start",
"type": "boolean"
},
"expiry_interval": {
"description": "Expiry Interval",
"type": "integer"
},
"is_bridge": {
"default": false,
"description": "Is Bridge",
"type": "boolean"
},
"connected_at": {
"description": "The Time that this Client is Connected",
"type": "integer"
}
},
"type": "object"
},
"listeners.listener_id_status": {
"required": [
"bind",
"enable",
"name",
"type",
"id"
],
"properties": {
"id": {
"description": "Listener id",
"example": "tcp:demo",
"type": "string"
},
"type": {
"description": "Listener type",
"enum": [
"tcp",
"ssl",
"ws",
"wss",
"quic"
],
"type": "string"
},
"name": {
"description": "Listener name",
"type": "string"
},
"enable": {
"description": "Listener enable",
"type": "boolean"
},
"number": {
"description": "ListenerId counter",
"minimum": 1,
"type": "integer"
},
"bind": {
"description": "Listener bind addr",
"example": "127.0.0.1:80",
"type": "string"
},
"acceptors": {
"description": "ListenerId acceptors",
"minimum": 1,
"type": "integer"
},
"status": {
"$ref": "#/components/schemas/listeners.status"
},
"node_status": {
"items": {
"$ref": "#/components/schemas/listeners.node_status"
},
"type": "array"
}
},
"type": "object"
},
"emqx_dashboard_monitor_api.sampler_current": {
"properties": {
"dropped_msg_rate": {
"description": "Dropped messages per 10 seconds",
"type": "integer"
},
"received_msg_rate": {
"description": "Dropped messages per 10 seconds",
"type": "integer"
},
"sent_msg_rate": {
"description": "Sent messages per 10 seconds",
"type": "integer"
},
"subscriptions": {
"description": "Subscriptions at the time of sampling. Can only represent the approximate state",
"type": "integer"
},
"topics": {
"description": "Count topics at the time of sampling. Can only represent the approximate state",
"type": "integer"
},
"connections": {
"description": "Connections at the time of sampling. Can only represent the approximate state",
"type": "integer"
}
},
"type": "object"
},
"emqx_telemetry_api.telemetry": {
"properties": {
"emqx_version": {
"description": "Get emqx version",
"example": "5.0.0-beta.3-32d1547c",
"type": "string"
},
"license": {
"description": "Get license information",
"example": {
"edition": "opensource"
},
"type": "object"
},
"os_name": {
"description": "Get OS name",
"example": "Linux",
"type": "string"
},
"os_version": {
"description": "Get OS version",
"example": "20.04",
"type": "string"
},
"otp_version": {
"description": "Get Erlang OTP version",
"example": "24",
"type": "string"
},
"up_time": {
"description": "Get uptime",
"example": 20220113,
"type": "integer"
},
"uuid": {
"description": "Get UUID",
"example": "AAAAAAAA-BBBB-CCCC-2022-DDDDEEEEFFF",
"type": "string"
},
"nodes_uuid": {
"description": "Get nodes UUID",
"example": [
"AAAAAAAA-BBBB-CCCC-2022-DDDDEEEEFFF",
"ZZZZZZZZ-CCCC-BBBB-2022-DDDDEEEEFFF"
],
"items": {
"type": "string"
},
"type": "array"
},
"active_plugins": {
"description": "Get active plugins",
"example": [
"Plugin A",
"Plugin B"
],
"items": {
"type": "string"
},
"type": "array"
},
"active_modules": {
"description": "Get active modules",
"example": [
"Module A",
"Module B"
],
"items": {
"type": "string"
},
"type": "array"
},
"num_clients": {
"description": "Get number of clients",
"example": 20220113,
"type": "integer"
},
"messages_received": {
"description": "Get number of messages received",
"example": 2022,
"type": "integer"
},
"messages_sent": {
"description": "Get number of messages sent",
"example": 2022,
"type": "integer"
}
},
"type": "object"
},
"listeners.node_status": {
"properties": {
"node": {
"description": "Node name",
"example": "emqx@127.0.0.1",
"type": "string"
},
"status": {
"$ref": "#/components/schemas/listeners.status"
}
},
"type": "object"
},
"emqx_mgmt_api_clients.client": {
"properties": {
"awaiting_rel_cnt": {
"description": "v4 api name [awaiting_rel] Number of awaiting PUBREC packet",
"type": "integer"
},
"awaiting_rel_max": {
"description": "v4 api name [max_awaiting_rel]. Maximum allowed number of awaiting PUBREC packet",
"type": "integer"
},
"clean_start": {
"description": "Indicate whether the client is using a brand new session",
"type": "boolean"
},
"clientid": {
"description": "Client identifier",
"type": "string"
},
"connected": {
"description": "Whether the client is connected",
"type": "boolean"
},
"connected_at": {
"description": "Client connection time, rfc3339 or timestamp(millisecond)",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"created_at": {
"description": "Session creation time, rfc3339 or timestamp(millisecond)",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"disconnected_at": {
"description": "Client offline time. It's Only valid and returned when connected is false, rfc3339 or timestamp(millisecond)",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"expiry_interval": {
"description": "Session expiration interval, with the unit of second",
"type": "integer"
},
"heap_size": {
"description": "Process heap size with the unit of byte",
"type": "integer"
},
"inflight_cnt": {
"description": "Current length of inflight",
"type": "integer"
},
"inflight_max": {
"description": "v4 api name [max_inflight]. Maximum length of inflight",
"type": "integer"
},
"ip_address": {
"description": "Client's IP address",
"type": "string"
},
"is_bridge": {
"description": "Indicates whether the client is connectedvia bridge",
"type": "boolean"
},
"keepalive": {
"description": "keepalive time, with the unit of second",
"type": "integer"
},
"mailbox_len": {
"description": "Process mailbox size",
"type": "integer"
},
"mqueue_dropped": {
"description": "Number of messages dropped by the message queue due to exceeding the length",
"type": "integer"
},
"mqueue_len": {
"description": "Current length of message queue",
"type": "integer"
},
"mqueue_max": {
"description": "v4 api name [max_mqueue]. Maximum length of message queue",
"type": "integer"
},
"node": {
"description": "Name of the node to which the client is connected",
"type": "string"
},
"port": {
"description": "Client's port",
"type": "integer"
},
"proto_name": {
"description": "Client protocol name",
"type": "string"
},
"proto_ver": {
"description": "Protocol version used by the client",
"type": "integer"
},
"recv_cnt": {
"description": "Number of TCP packets received",
"type": "integer"
},
"recv_msg": {
"description": "Number of PUBLISH packets received",
"type": "integer"
},
"recv_msg.dropped": {
"description": "Number of dropped PUBLISH packets",
"type": "integer"
},
"recv_msg.dropped.await_pubrel_timeout": {
"description": "Number of dropped PUBLISH packets due to expired",
"type": "integer"
},
"recv_msg.qos0": {
"description": "Number of PUBLISH QoS0 packets received",
"type": "integer"
},
"recv_msg.qos1": {
"description": "Number of PUBLISH QoS1 packets received",
"type": "integer"
},
"recv_msg.qos2": {
"description": "Number of PUBLISH QoS2 packets received",
"type": "integer"
},
"recv_oct": {
"description": "Number of bytes received",
"type": "integer"
},
"recv_pkt": {
"description": "Number of MQTT packets received",
"type": "integer"
},
"reductions": {
"description": "Erlang reduction",
"type": "integer"
},
"send_cnt": {
"description": "Number of TCP packets sent",
"type": "integer"
},
"send_msg": {
"description": "Number of PUBLISH packets sent",
"type": "integer"
},
"send_msg.dropped": {
"description": "Number of dropped PUBLISH packets",
"type": "integer"
},
"send_msg.dropped.expired": {
"description": "Number of dropped PUBLISH packets due to expired",
"type": "integer"
},
"send_msg.dropped.queue_full": {
"description": "Number of dropped PUBLISH packets due to queue full",
"type": "integer"
},
"send_msg.dropped.too_large": {
"description": "Number of dropped PUBLISH packets due to packet length too large",
"type": "integer"
},
"send_msg.qos0": {
"description": "Number of PUBLISH QoS0 packets sent",
"type": "integer"
},
"send_msg.qos1": {
"description": "Number of PUBLISH QoS1 packets sent",
"type": "integer"
},
"send_msg.qos2": {
"description": "Number of PUBLISH QoS2 packets sent",
"type": "integer"
},
"send_oct": {
"description": "Number of bytes sent",
"type": "integer"
},
"send_pkt": {
"description": "Number of MQTT packets sent",
"type": "integer"
},
"subscriptions_cnt": {
"description": "Number of subscriptions established by this client.",
"type": "integer"
},
"subscriptions_max": {
"description": "v4 api name [max_subscriptions] Maximum number of subscriptions allowed by this client",
"type": "integer"
},
"username": {
"description": "User name of client when connecting",
"type": "string"
},
"mountpoint": {
"description": "Topic mountpoint",
"type": "string"
},
"zone": {
"description": "Indicate the configuration group used by the client",
"type": "string"
}
},
"type": "object"
},
"bridge_mqtt.get": {
"required": [
"server"
],
"properties": {
"status": {
"description": "The status of the bridge",
"enum": [
"connected",
"disconnected",
"connecting"
],
"type": "string"
},
"node_status": {
"description": "Node status.",
"items": {
"$ref": "#/components/schemas/bridge.node_status"
},
"type": "array"
},
"enable": {
"default": true,
"description": "Enable or disable this bridge",
"type": "boolean"
},
"resource_opts": {
"default": {},
"description": "Resource options.",
"$ref": "#/components/schemas/bridge_mqtt.creation_opts"
},
"mode": {
"default": "cluster_shareload",
"description": "
The mode of the MQTT Bridge.
- cluster_shareload: create an MQTT connection on each node in the emqx cluster.
In 'cluster_shareload' mode, the incoming load from the remote broker is shared by
using shared subscription.
Note that the 'clientid' is suffixed by the node name, this is to avoid
clientid conflicts between different nodes. And we can only use shared subscription
topic filters for remote.topic of ingress connections.
",
"enum": [
"cluster_shareload"
],
"type": "string"
},
"server": {
"description": "The host and port of the remote MQTT broker",
"type": "string"
},
"clientid_prefix": {
"description": "Optional prefix to prepend to the clientid used by egress bridges.",
"type": "string"
},
"proto_ver": {
"default": "v4",
"description": "The MQTT protocol version",
"enum": [
"v3",
"v4",
"v5"
],
"type": "string"
},
"bridge_mode": {
"default": false,
"description": "
If enable bridge mode.
NOTE: This setting is only for MQTT protocol version older than 5.0, and the remote MQTT
broker MUST support this feature.
",
"type": "boolean"
},
"username": {
"description": "The username of the MQTT protocol",
"type": "string"
},
"password": {
"description": "The password of the MQTT protocol",
"format": "password",
"type": "string"
},
"clean_start": {
"default": true,
"deprecated": "since(\"v5.0.16\")",
"description": "The clean-start or the clean-session of the MQTT protocol",
"type": "boolean"
},
"keepalive": {
"default": "300s",
"description": "MQTT Keepalive. Time interval is a string that contains a number followed by time unit:
- `ms` for milliseconds,
- `s` for seconds,
- `m` for minutes,
- `h` for hours;
or combination of whereof: `1h5m0s`",
"type": "string"
},
"retry_interval": {
"default": "15s",
"description": "Message retry interval. Delay for the MQTT bridge to retry sending the QoS1/QoS2 messages in case of ACK not received. Time interval is a string that contains a number followed by time unit:
- `ms` for milliseconds,
- `s` for seconds,
- `m` for minutes,
- `h` for hours;
or combination of whereof: `1h5m0s`",
"type": "string"
},
"max_inflight": {
"default": 32,
"description": "Max inflight (sent, but un-acked) messages of the MQTT protocol",
"minimum": 0,
"type": "integer"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
},
"ingress": {
"description": "The ingress config defines how this bridge receive messages from the remote MQTT broker, and then
send them to the local broker.
Template with variables is allowed in 'remote.qos', 'local.topic', 'local.qos', 'local.retain', 'local.payload'.
NOTE: if this bridge is used as the input of a rule, and also 'local.topic' is
configured, then messages got from the remote broker will be sent to both the 'local.topic' and
the rule.",
"$ref": "#/components/schemas/connector-mqtt.ingress"
},
"egress": {
"description": "The egress config defines how this bridge forwards messages from the local broker to the remote broker.
Template with variables is allowed in 'remote.topic', 'local.qos', 'local.retain', 'local.payload'.
NOTE: if this bridge is used as the action of a rule, and also 'local.topic'
is configured, then both the data got from the rule and the MQTT messages that matches
'local.topic' will be forwarded.",
"$ref": "#/components/schemas/connector-mqtt.egress"
}
},
"type": "object"
},
"authz.resource_metrics": {
"properties": {
"matched": {
"description": "Count of this resource is queried.",
"type": "integer"
},
"success": {
"description": "Count of query success.",
"type": "integer"
},
"failed": {
"description": "Count of query failed.",
"type": "integer"
},
"rate": {
"description": "The rate of matched, times/second.",
"type": "number"
},
"rate_max": {
"description": "The max rate of matched, times/second.",
"type": "number"
},
"rate_last5m": {
"description": "The average rate of matched in the last 5 minutes, times/second.",
"type": "number"
}
},
"type": "object"
},
"emqx_mgmt_api_subscriptions.subscription": {
"properties": {
"node": {
"description": "Access type",
"type": "string"
},
"topic": {
"description": "Topic name",
"type": "string"
},
"clientid": {
"description": "Client identifier",
"type": "string"
},
"qos": {
"description": "QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
},
"nl": {
"description": "No Local",
"type": "integer"
},
"rap": {
"description": "Retain as Published",
"type": "integer"
},
"rh": {
"description": "Retain Handling",
"type": "integer"
}
},
"type": "object"
},
"emqx_conf_schema.cluster_mcast": {
"properties": {
"addr": {
"default": "239.192.0.1",
"description": "Multicast IPv4 address.",
"readOnly": true,
"type": "string"
},
"ports": {
"default": [
4369,
4370
],
"description": "List of UDP ports used for service discovery.
Note: probe messages are broadcast to all the specified ports.
",
"items": {
"type": "integer"
},
"readOnly": true,
"type": "array"
},
"iface": {
"default": "0.0.0.0",
"description": "Local IP address the node discovery service needs to bind to.",
"readOnly": true,
"type": "string"
},
"ttl": {
"default": 255,
"description": "Time-to-live (TTL) for the outgoing UDP datagrams.",
"maximum": 255,
"minimum": 0,
"readOnly": true,
"type": "integer"
},
"loop": {
"default": true,
"description": "If true, loop UDP datagrams back to the local socket.",
"readOnly": true,
"type": "boolean"
},
"sndbuf": {
"default": "16KB",
"description": "Size of the kernel-level buffer for outgoing datagrams.",
"example": "32MB",
"readOnly": true,
"type": "string"
},
"recbuf": {
"default": "16KB",
"description": "Size of the kernel-level buffer for incoming datagrams.",
"example": "32MB",
"readOnly": true,
"type": "string"
},
"buffer": {
"default": "32KB",
"description": "Size of the user-level buffer.",
"example": "32MB",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"emqx_gateway_api_listeners.ssl_listener": {
"properties": {
"id": {
"description": "Listener ID",
"type": "string"
},
"type": {
"description": "Listener Type",
"enum": [
"ssl"
],
"type": "string"
},
"name": {
"description": "Listener Name",
"type": "string"
},
"running": {
"description": "Listener Running status",
"type": "boolean"
},
"acceptors": {
"default": 16,
"description": "Size of the acceptor pool.",
"type": "integer"
},
"tcp_options": {
"description": "Setting the TCP socket options.",
"$ref": "#/components/schemas/broker.tcp_opts"
},
"proxy_protocol": {
"default": false,
"description": "Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "15s",
"description": "Timeout for proxy protocol.
EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.",
"example": "12m",
"type": "string"
},
"enable": {
"default": true,
"description": "Enable the listener.",
"type": "boolean"
},
"bind": {
"description": "The IP address and port that the listener will bind.",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"max_connections": {
"default": 1024,
"description": "Maximum number of concurrent connections.",
"type": "integer"
},
"max_conn_rate": {
"default": 1000,
"description": "Maximum connections per second.",
"type": "integer"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"enable_authn": {
"default": true,
"description": "Set true (default) to enable client authentication on this listener.
When set to false clients will be allowed to connect without authentication.",
"type": "boolean"
},
"mountpoint": {
"description": "When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint` set to `some_tenant`, then the client actually subscribes to the topic `some_tenant/t`. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic `t`, the message is routed to all the clients subscribed `some_tenant/t`, so client A will receive the message, with topic name `t`. Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"access_rules": {
"default": "",
"description": "The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny",
"items": {
"type": "string"
},
"type": "array"
},
"ssl_options": {
"description": "SSL Socket options.",
"$ref": "#/components/schemas/broker.listener_ssl_opts"
},
"status": {
"description": "listener status ",
"$ref": "#/components/schemas/listeners.status"
},
"node_status": {
"description": "listener status of each node in the cluster",
"items": {
"$ref": "#/components/schemas/listeners.node_status"
},
"type": "array"
}
},
"type": "object"
},
"zone.mqtt": {
"properties": {
"idle_timeout": {
"description": "After the TCP connection is established, if the MQTT CONNECT packet from the client is
not received within the time specified by idle_timeout, the connection will be disconnected.
After the CONNECT packet has been accepted by EMQX, if the connection idles for this long time,
then the Erlang process is put to hibernation to save OS resources. Note: long idle_timeout
interval may impose risk at the system if large number of malicious clients only establish connections
but do not send any data.",
"oneOf": [
{
"example": "12m",
"type": "string"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"max_packet_size": {
"description": "Maximum MQTT packet size allowed.",
"example": "32MB",
"type": "string"
},
"max_clientid_len": {
"description": "Maximum allowed length of MQTT Client ID.",
"maximum": 65535,
"minimum": 23,
"type": "integer"
},
"max_topic_levels": {
"description": "Maximum topic levels allowed.",
"maximum": 65535,
"minimum": 1,
"type": "integer"
},
"max_qos_allowed": {
"description": "Maximum QoS allowed.",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
},
"max_topic_alias": {
"description": "Maximum topic alias, 0 means no topic alias supported.",
"maximum": 65535,
"minimum": 0,
"type": "integer"
},
"retain_available": {
"description": "Whether to enable support for MQTT retained message.",
"type": "boolean"
},
"wildcard_subscription": {
"description": "Whether to enable support for MQTT wildcard subscription.",
"type": "boolean"
},
"shared_subscription": {
"description": "Whether to enable support for MQTT shared subscription.",
"type": "boolean"
},
"exclusive_subscription": {
"description": "Whether to enable support for MQTT exclusive subscription.",
"type": "boolean"
},
"ignore_loop_deliver": {
"description": "Ignore loop delivery of messages for MQTT v3.1.1/v3.1.0, similar to No Local subscription option in MQTT 5.0.",
"type": "boolean"
},
"strict_mode": {
"description": "Parse MQTT messages in strict mode.
When set to true, invalid utf8 strings in for example client ID, topic name, etc. will cause the client to be disconnected",
"type": "boolean"
},
"response_information": {
"description": "Specify the response information returned to the client. This feature is disabled if is set to \"\". Applies only to clients using MQTT 5.0.",
"type": "string"
},
"server_keepalive": {
"description": "The keep alive that EMQX requires the client to use. If configured as disabled, it means that the keep alive specified by the client will be used. Requires Server Keep Alive in MQTT 5.0, so it is only applicable to clients using MQTT 5.0 protocol.",
"oneOf": [
{
"enum": [
"disabled"
],
"type": "string"
},
{
"type": "integer"
}
]
},
"keepalive_backoff": {
"description": "The backoff multiplier used by the broker to determine the client keep alive timeout. If EMQX doesn't receive any packet in Keep Alive * Backoff * 2 seconds, EMQX will close the current connection.",
"type": "number"
},
"max_subscriptions": {
"description": "Maximum number of subscriptions allowed per client.",
"oneOf": [
{
"enum": [
"infinity"
],
"type": "string"
},
{
"minimum": 1,
"type": "integer"
}
]
},
"upgrade_qos": {
"description": "Force upgrade of QoS level according to subscription.",
"type": "boolean"
},
"max_inflight": {
"description": "Maximum number of QoS 1 and QoS 2 messages that are allowed to be delivered simultaneously before completing the acknowledgment.",
"maximum": 65535,
"minimum": 1,
"type": "integer"
},
"retry_interval": {
"description": "Retry interval for QoS 1/2 message delivering.",
"example": "12m",
"type": "string"
},
"max_awaiting_rel": {
"description": "For each publisher session, the maximum number of outstanding QoS 2 messages pending on the client to send PUBREL. After reaching this limit, new QoS 2 PUBLISH requests will be rejected with `147(0x93)` until either PUBREL is received or timed out.",
"oneOf": [
{
"enum": [
"infinity"
],
"type": "string"
},
{
"type": "integer"
}
]
},
"await_rel_timeout": {
"description": "For client to broker QoS 2 message, the time limit for the broker to wait before the `PUBREL` message is received. The wait is aborted after timed out, meaning the packet ID is freed for new `PUBLISH` requests. Receiving a stale `PUBREL` causes a warning level log. Note, the message is delivered to subscribers before entering the wait for PUBREL.",
"example": "12m",
"type": "string"
},
"session_expiry_interval": {
"description": "Specifies how long the session will expire after the connection is disconnected, only for non-MQTT 5.0 connections.",
"example": "12m",
"type": "string"
},
"max_mqueue_len": {
"description": "Maximum queue length. Enqueued messages when persistent client disconnected, or inflight window is full.",
"oneOf": [
{
"enum": [
"infinity"
],
"type": "string"
},
{
"minimum": 0,
"type": "integer"
}
]
},
"mqueue_priorities": {
"description": "Topic priorities. Priority number [1-255]
There's no priority table by default, hence all messages are treated equal.
**NOTE**: Comma and equal signs are not allowed for priority topic names.
**NOTE**: Messages for topics not in the priority table are treated as either highest or lowest priority depending on the configured value for mqtt.mqueue_default_priority.
**Examples**:
To configure \"topic/1\" > \"topic/2\":
mqueue_priorities: {\"topic/1\": 10, \"topic/2\": 8}
",
"oneOf": [
{
"enum": [
"disabled"
],
"type": "string"
},
{
"example": {},
"type": "object"
}
]
},
"mqueue_default_priority": {
"description": "Default topic priority, which will be used by topics not in Topic Priorities (mqueue_priorities).",
"enum": [
"highest",
"lowest"
],
"type": "string"
},
"mqueue_store_qos0": {
"description": "Specifies whether to store QoS 0 messages in the message queue while the connection is down but the session remains.",
"type": "boolean"
},
"use_username_as_clientid": {
"description": "Whether to user Client ID as Username.
This setting takes effect later than Use Peer Certificate as Username (peer_cert_as_username) and Use peer certificate as Client ID (peer_cert_as_clientid).
",
"type": "boolean"
},
"peer_cert_as_username": {
"description": "Use the CN, DN field in the peer certificate or the entire certificate content as Username. Only works for the TLS connection.
Supported configurations are the following:
- cn: Take the CN field of the certificate as Username
- dn: Take the DN field of the certificate as Username
- crt: Take the content of the DER or PEM certificate as Username
- pem: Convert DER certificate content to PEM format as Username
- md5: Take the MD5 value of the content of the DER or PEM certificate as Username
",
"enum": [
"disabled",
"cn",
"dn",
"crt",
"pem",
"md5"
],
"type": "string"
},
"peer_cert_as_clientid": {
"description": "Use the CN, DN field in the peer certificate or the entire certificate content as Client ID. Only works for the TLS connection.
Supported configurations are the following:
- cn: Take the CN field of the certificate as Client ID
- dn: Take the DN field of the certificate as Client ID
- crt: Take the content of the DER or PEM certificate as Client ID
- pem: Convert DER certificate content to PEM format as Client ID
- md5: Take the MD5 value of the content of the DER or PEM certificate as Client ID
",
"enum": [
"disabled",
"cn",
"dn",
"crt",
"pem",
"md5"
],
"type": "string"
}
},
"type": "object"
},
"emqx_topic_metrics_api.topic_metrics": {
"required": [
"metrics",
"create_time",
"topic"
],
"properties": {
"topic": {
"description": "Topic",
"example": "testtopic/1",
"type": "string"
},
"create_time": {
"description": "Create time",
"example": "2022-01-14T21:48:47+08:00",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"reset_time": {
"description": "Reset time. In rfc3339. Nullable if never reset",
"example": "2022-01-14T21:48:47+08:00",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"metrics": {
"description": "Metrics",
"$ref": "#/components/schemas/emqx_topic_metrics_api.metrics"
}
},
"type": "object"
},
"listeners.quic_required_bind": {
"required": [
"bind",
"id",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"quic"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"id": {
"description": "Listener id",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"certfile": {
"description": "Path to the certificate file.",
"type": "string"
},
"keyfile": {
"description": "Path to the secret key file. ",
"type": "string"
},
"ciphers": {
"default": [
"TLS_AES_256_GCM_SHA384",
"TLS_AES_128_GCM_SHA256",
"TLS_CHACHA20_POLY1305_SHA256"
],
"description": "
This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\" or
[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"].
Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.
The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.
NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
PSK cipher suites: \"RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA\"
NOTE: QUIC listener supports only 'tlsv1.3' ciphers
",
"items": {
"type": "string"
},
"type": "array"
},
"idle_timeout": {
"default": 0,
"description": "How long a connection can go idle before it is gracefully shut down. 0 to disable",
"example": "32s",
"type": "string"
},
"handshake_idle_timeout": {
"default": "10s",
"description": "How long a handshake can idle before it is discarded. ",
"example": "32s",
"type": "string"
},
"keep_alive_interval": {
"default": 0,
"description": "
How often to send PING frames to keep a connection alive. 0 means disabled.
",
"example": "32s",
"type": "string"
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"bind": {
"default": 14567,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
}
},
"type": "object"
},
"emqx_authz_api_mnesia.username_response_data": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rules_for_username"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/public.meta"
}
},
"type": "object"
},
"authn-scram-builtin_db.authentication": {
"required": [
"backend",
"mechanism"
],
"properties": {
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"scram"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"built_in_database"
],
"type": "string"
},
"algorithm": {
"default": "sha256",
"description": "Hashing algorithm.",
"enum": [
"sha256",
"sha512"
],
"type": "string"
},
"iteration_count": {
"default": 4096,
"description": "Iteration count.",
"minimum": 0,
"type": "integer"
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
}
},
"type": "object"
},
"bridge_mqtt.post": {
"required": [
"server",
"name",
"type"
],
"properties": {
"type": {
"description": "The bridge type.",
"enum": [
"mqtt"
],
"type": "string"
},
"name": {
"description": "Bridge name, used as a human-readable description of the bridge.",
"type": "string"
},
"enable": {
"default": true,
"description": "Enable or disable this bridge",
"type": "boolean"
},
"resource_opts": {
"default": {},
"description": "Resource options.",
"$ref": "#/components/schemas/bridge_mqtt.creation_opts"
},
"mode": {
"default": "cluster_shareload",
"description": "
The mode of the MQTT Bridge.
- cluster_shareload: create an MQTT connection on each node in the emqx cluster.
In 'cluster_shareload' mode, the incoming load from the remote broker is shared by
using shared subscription.
Note that the 'clientid' is suffixed by the node name, this is to avoid
clientid conflicts between different nodes. And we can only use shared subscription
topic filters for remote.topic of ingress connections.
",
"enum": [
"cluster_shareload"
],
"type": "string"
},
"server": {
"description": "The host and port of the remote MQTT broker",
"type": "string"
},
"clientid_prefix": {
"description": "Optional prefix to prepend to the clientid used by egress bridges.",
"type": "string"
},
"proto_ver": {
"default": "v4",
"description": "The MQTT protocol version",
"enum": [
"v3",
"v4",
"v5"
],
"type": "string"
},
"bridge_mode": {
"default": false,
"description": "
If enable bridge mode.
NOTE: This setting is only for MQTT protocol version older than 5.0, and the remote MQTT
broker MUST support this feature.
",
"type": "boolean"
},
"username": {
"description": "The username of the MQTT protocol",
"type": "string"
},
"password": {
"description": "The password of the MQTT protocol",
"format": "password",
"type": "string"
},
"clean_start": {
"default": true,
"deprecated": "since(\"v5.0.16\")",
"description": "The clean-start or the clean-session of the MQTT protocol",
"type": "boolean"
},
"keepalive": {
"default": "300s",
"description": "MQTT Keepalive. Time interval is a string that contains a number followed by time unit:
- `ms` for milliseconds,
- `s` for seconds,
- `m` for minutes,
- `h` for hours;
or combination of whereof: `1h5m0s`",
"type": "string"
},
"retry_interval": {
"default": "15s",
"description": "Message retry interval. Delay for the MQTT bridge to retry sending the QoS1/QoS2 messages in case of ACK not received. Time interval is a string that contains a number followed by time unit:
- `ms` for milliseconds,
- `s` for seconds,
- `m` for minutes,
- `h` for hours;
or combination of whereof: `1h5m0s`",
"type": "string"
},
"max_inflight": {
"default": 32,
"description": "Max inflight (sent, but un-acked) messages of the MQTT protocol",
"minimum": 0,
"type": "integer"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
},
"ingress": {
"description": "The ingress config defines how this bridge receive messages from the remote MQTT broker, and then
send them to the local broker.
Template with variables is allowed in 'remote.qos', 'local.topic', 'local.qos', 'local.retain', 'local.payload'.
NOTE: if this bridge is used as the input of a rule, and also 'local.topic' is
configured, then messages got from the remote broker will be sent to both the 'local.topic' and
the rule.",
"$ref": "#/components/schemas/connector-mqtt.ingress"
},
"egress": {
"description": "The egress config defines how this bridge forwards messages from the local broker to the remote broker.
Template with variables is allowed in 'remote.topic', 'local.qos', 'local.retain', 'local.payload'.
NOTE: if this bridge is used as the action of a rule, and also 'local.topic'
is configured, then both the data got from the rule and the MQTT messages that matches
'local.topic' will be forwarded.",
"$ref": "#/components/schemas/connector-mqtt.egress"
}
},
"type": "object"
},
"plugins.plugin": {
"required": [
"running_status",
"description",
"rel_apps",
"rel_vsn",
"name"
],
"properties": {
"name": {
"description": "Name-Vsn: without .tar.gz",
"example": "emqx_plugin_template-5.0-rc.1",
"type": "string"
},
"author": {
"example": [
"EMQX Team"
],
"items": {
"type": "string"
},
"type": "array"
},
"builder": {
"$ref": "#/components/schemas/plugins.builder"
},
"built_on_otp_release": {
"example": "24",
"type": "string"
},
"compatibility": {
"example": {
"emqx": "~>5.0"
},
"type": "object"
},
"git_commit_or_build_date": {
"description": "Last git commit date by `git log -1 --pretty=format:'%cd' --date=format:'%Y-%m-%d`.
If the last commit date is not available, the build date will be presented.",
"example": "2021-12-25",
"type": "string"
},
"functionality": {
"example": [
"Demo"
],
"items": {
"type": "string"
},
"type": "array"
},
"git_ref": {
"example": "ddab50fafeed6b1faea70fc9ffd8c700d7e26ec1",
"type": "string"
},
"metadata_vsn": {
"example": "0.1.0",
"type": "string"
},
"rel_vsn": {
"description": "Plugins release version",
"example": "5.0-rc.1",
"type": "string"
},
"rel_apps": {
"description": "Aplications in plugin.",
"example": [
"emqx_plugin_template-5.0.0",
"map_sets-1.1.0"
],
"items": {
"type": "string"
},
"type": "array"
},
"repo": {
"example": "https://github.com/emqx/emqx-plugin-template",
"type": "string"
},
"description": {
"description": "Plugin description.",
"example": "This is an demo plugin description",
"type": "string"
},
"running_status": {
"items": {
"$ref": "#/components/schemas/plugins.running_status"
},
"type": "array"
},
"readme": {
"description": "only return when `GET /plugins/{name}`.",
"example": "This is an demo plugin.",
"type": "string"
}
},
"type": "object"
},
"zone.conn_congestion": {
"properties": {
"enable_alarm": {
"description": "Enable or disable connection congestion alarm.",
"type": "boolean"
},
"min_alarm_sustain_duration": {
"description": "Minimal time before clearing the alarm.
The alarm is cleared only when there's no pending data in
the queue, and at least min_alarm_sustain_durationmilliseconds passed since the last time we considered the connection 'congested'.
This is to avoid clearing and raising the alarm again too often.",
"example": "12m",
"type": "string"
}
},
"type": "object"
},
"emqx_authz_api_mnesia.rules_for_clientid": {
"required": [
"clientid"
],
"properties": {
"rules": {
"items": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rule_item"
},
"type": "array"
},
"clientid": {
"description": "ClientID",
"example": "client1",
"type": "string"
}
},
"type": "object"
},
"emqx_rule_api_schema.ctx_pub": {
"required": [
"event_type"
],
"properties": {
"event_type": {
"description": "Event Type",
"enum": [
"message_publish"
],
"type": "string"
},
"id": {
"description": "Message ID",
"type": "string"
},
"clientid": {
"description": "The Client ID",
"type": "string"
},
"username": {
"description": "The User Name",
"type": "string"
},
"payload": {
"description": "The Message Payload",
"type": "string"
},
"peerhost": {
"description": "The IP Address of the Peer Client",
"type": "string"
},
"topic": {
"description": "Message Topic",
"type": "string"
},
"publish_received_at": {
"description": "The Time that this Message is Received",
"type": "integer"
},
"qos": {
"description": "The Message QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"emqx_gateway_api_clients.coap_client": {
"properties": {
"node": {
"description": "Name of the node to which the client is connected",
"type": "string"
},
"clientid": {
"description": "Client ID",
"type": "string"
},
"username": {
"description": "Username of client when connecting",
"type": "string"
},
"mountpoint": {
"description": "Topic mountpoint",
"type": "string"
},
"proto_name": {
"description": "Client protocol name",
"type": "string"
},
"proto_ver": {
"description": "Protocol version used by the client",
"type": "string"
},
"ip_address": {
"description": "Client's IP address",
"type": "string"
},
"port": {
"description": "Client's port",
"type": "integer"
},
"is_bridge": {
"description": "Indicates whether the client is connected via bridge",
"type": "boolean"
},
"connected_at": {
"description": "Client connection time",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"disconnected_at": {
"description": "Client offline time, This field is only valid and returned when connected is false",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"connected": {
"description": "Whether the client is connected",
"type": "boolean"
},
"keepalive": {
"description": "Keepalive time, with the unit of second",
"type": "integer"
},
"clean_start": {
"description": "Indicate whether the client is using a brand new session",
"type": "boolean"
},
"expiry_interval": {
"description": "Session expiration interval, with the unit of second",
"type": "integer"
},
"created_at": {
"description": "Session creation time",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"subscriptions_cnt": {
"description": "Number of subscriptions established by this client",
"type": "integer"
},
"subscriptions_max": {
"description": "Maximum number of subscriptions allowed by this client",
"type": "integer"
},
"inflight_cnt": {
"description": "Current length of inflight",
"type": "integer"
},
"inflight_max": {
"description": "Maximum length of inflight",
"type": "integer"
},
"mqueue_len": {
"description": "Current length of message queue",
"type": "integer"
},
"mqueue_max": {
"description": "Maximum length of message queue",
"type": "integer"
},
"mqueue_dropped": {
"description": "Number of messages dropped by the message queue due to exceeding the length",
"type": "integer"
},
"awaiting_rel_cnt": {
"description": "Number of awaiting acknowledge packet",
"type": "integer"
},
"awaiting_rel_max": {
"description": "Maximum allowed number of awaiting PUBREC packet",
"type": "integer"
},
"recv_oct": {
"description": "Number of bytes received",
"type": "integer"
},
"recv_cnt": {
"description": "Number of socket packets received",
"type": "integer"
},
"recv_pkt": {
"description": "Number of protocol packets received",
"type": "integer"
},
"recv_msg": {
"description": "Number of message packets received",
"type": "integer"
},
"send_oct": {
"description": "Number of bytes sent",
"type": "integer"
},
"send_cnt": {
"description": "Number of socket packets sent",
"type": "integer"
},
"send_pkt": {
"description": "Number of protocol packets sent",
"type": "integer"
},
"send_msg": {
"description": "Number of message packets sent",
"type": "integer"
},
"mailbox_len": {
"description": "Process mailbox size",
"type": "integer"
},
"heap_size": {
"description": "Process heap size with the unit of byte",
"type": "integer"
},
"reductions": {
"description": "Erlang reduction",
"type": "integer"
}
},
"type": "object"
},
"emqx_mgmt_api_clients.authz_cache": {
"properties": {
"access": {
"description": "Access type",
"type": "string"
},
"result": {
"description": "Allow or deny",
"type": "string"
},
"topic": {
"description": "Topic name",
"type": "string"
},
"updated_time": {
"description": "Update time",
"type": "integer"
}
},
"type": "object"
},
"emqx_rule_api_schema.rule_test": {
"required": [
"sql"
],
"properties": {
"context": {
"default": {},
"description": "The context of the event for testing",
"oneOf": [
{
"$ref": "#/components/schemas/emqx_rule_api_schema.ctx_bridge_mqtt"
},
{
"$ref": "#/components/schemas/emqx_rule_api_schema.ctx_check_authz_complete"
},
{
"$ref": "#/components/schemas/emqx_rule_api_schema.ctx_connack"
},
{
"$ref": "#/components/schemas/emqx_rule_api_schema.ctx_disconnected"
},
{
"$ref": "#/components/schemas/emqx_rule_api_schema.ctx_connected"
},
{
"$ref": "#/components/schemas/emqx_rule_api_schema.ctx_dropped"
},
{
"$ref": "#/components/schemas/emqx_rule_api_schema.ctx_acked"
},
{
"$ref": "#/components/schemas/emqx_rule_api_schema.ctx_delivered"
},
{
"$ref": "#/components/schemas/emqx_rule_api_schema.ctx_unsub"
},
{
"$ref": "#/components/schemas/emqx_rule_api_schema.ctx_sub"
},
{
"$ref": "#/components/schemas/emqx_rule_api_schema.ctx_pub"
}
]
},
"sql": {
"description": "The SQL of the rule for testing",
"type": "string"
}
},
"type": "object"
},
"slow_subs.slow_subs": {
"properties": {
"enable": {
"default": false,
"description": "Enable this feature",
"type": "boolean"
},
"threshold": {
"default": "500ms",
"description": "The latency threshold for statistics",
"example": "32s",
"type": "string"
},
"expire_interval": {
"default": "300s",
"description": "The eviction time of the record, which in the statistics record table",
"example": "32s",
"type": "string"
},
"top_k_num": {
"default": 10,
"description": "The maximum number of records in the slow subscription statistics record table",
"minimum": 1,
"type": "integer"
},
"stats_type": {
"default": "whole",
"description": "The method to calculate the latency",
"enum": [
"whole",
"internal",
"response"
],
"type": "string"
}
},
"type": "object"
},
"emqx_rule_api_schema.ctx_dropped": {
"required": [
"event_type"
],
"properties": {
"event_type": {
"description": "Event Type",
"enum": [
"message_dropped"
],
"type": "string"
},
"id": {
"description": "Message ID",
"type": "string"
},
"reason": {
"description": "The Reason for Dropping",
"type": "string"
},
"clientid": {
"description": "The Client ID",
"type": "string"
},
"username": {
"description": "The User Name",
"type": "string"
},
"payload": {
"description": "The Message Payload",
"type": "string"
},
"peerhost": {
"description": "The IP Address of the Peer Client",
"type": "string"
},
"topic": {
"description": "Message Topic",
"type": "string"
},
"publish_received_at": {
"description": "The Time that this Message is Received",
"type": "integer"
},
"qos": {
"description": "The Message QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"limiter.client_fields": {
"properties": {
"bytes_in": {
"default": {},
"description": "The bytes_in limiter.
This is used to limit the inbound bytes rate for this EMQX node.
Once the limit is reached, the restricted client will be slow down even be hung for a while.",
"$ref": "#/components/schemas/limiter.client_opts"
},
"message_in": {
"default": {},
"description": "The message in limiter.
This is used to limit the inbound message numbers for this EMQX node
Once the limit is reached, the restricted client will be slow down even be hung for a while.",
"$ref": "#/components/schemas/limiter.client_opts"
},
"connection": {
"default": {},
"description": "The connection limiter.
This is used to limit the connection rate for this EMQX node.
Once the limit is reached, new connections will be refused",
"$ref": "#/components/schemas/limiter.client_opts"
},
"message_routing": {
"default": {},
"description": "The message routing limiter.
This is used to limit the forwarding rate for this EMQX node.
Once the limit is reached, new publish will be refused",
"$ref": "#/components/schemas/limiter.client_opts"
},
"internal": {
"default": {},
"description": "Limiter for EMQX internal app.",
"$ref": "#/components/schemas/limiter.client_opts"
}
},
"type": "object"
},
"limiter.limiter": {
"properties": {
"bytes_in": {
"default": {},
"description": "The bytes_in limiter.
This is used to limit the inbound bytes rate for this EMQX node.
Once the limit is reached, the restricted client will be slow down even be hung for a while.",
"$ref": "#/components/schemas/limiter.node_opts"
},
"message_in": {
"default": {},
"description": "The message in limiter.
This is used to limit the inbound message numbers for this EMQX node
Once the limit is reached, the restricted client will be slow down even be hung for a while.",
"$ref": "#/components/schemas/limiter.node_opts"
},
"connection": {
"default": {},
"description": "The connection limiter.
This is used to limit the connection rate for this EMQX node.
Once the limit is reached, new connections will be refused",
"$ref": "#/components/schemas/limiter.node_opts"
},
"message_routing": {
"default": {},
"description": "The message routing limiter.
This is used to limit the forwarding rate for this EMQX node.
Once the limit is reached, new publish will be refused",
"$ref": "#/components/schemas/limiter.node_opts"
},
"internal": {
"default": {},
"description": "Limiter for EMQX internal app.",
"$ref": "#/components/schemas/limiter.node_opts"
},
"client": {
"default": {
"bytes_in": {},
"connection": {},
"internal": {},
"message_in": {},
"message_routing": {}
},
"description": "The rate limit for each user of the bucket",
"$ref": "#/components/schemas/limiter.client_fields"
}
},
"type": "object"
},
"broker.ws_opts": {
"properties": {
"mqtt_path": {
"default": "/mqtt",
"description": "
WebSocket's MQTT protocol path. So the address of EMQX Broker's WebSocket is:
ws://{ip}:{port}/mqtt
",
"type": "string"
},
"mqtt_piggyback": {
"default": "multiple",
"description": "
Whether a WebSocket message is allowed to contain multiple MQTT packets.
",
"enum": [
"single",
"multiple"
],
"type": "string"
},
"compress": {
"default": false,
"description": "
If true, compress WebSocket messages using zlib.
The configuration items under deflate_opts belong to the compression-related parameter configuration.
",
"type": "boolean"
},
"idle_timeout": {
"default": "7200s",
"description": "
Close transport-layer connections from the clients that have not sent MQTT CONNECT
message within this interval.
",
"example": "12m",
"type": "string"
},
"max_frame_size": {
"default": "infinity",
"description": "
The maximum length of a single MQTT packet.
",
"oneOf": [
{
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"fail_if_no_subprotocol": {
"default": true,
"description": "
If true, the server will return an error when
the client does not carry the Sec-WebSocket-Protocol field.
Note: WeChat applet needs to disable this verification.
",
"type": "boolean"
},
"supported_subprotocols": {
"default": "mqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5",
"description": "
Comma-separated list of supported subprotocols.
",
"example": "item1,item2",
"type": "string"
},
"check_origin_enable": {
"default": false,
"description": "
If true, origin HTTP header will be
validated against the list of allowed origins configured in check_origins
parameter.
",
"type": "boolean"
},
"allow_origin_absence": {
"default": true,
"description": "
If false and check_origin_enable is
true, the server will reject requests that don't have origin
HTTP header.
",
"type": "boolean"
},
"check_origins": {
"default": "http://localhost:18083, http://127.0.0.1:18083",
"description": "
List of allowed origins.
See check_origin_enable.
",
"example": "item1,item2",
"type": "string"
},
"proxy_address_header": {
"default": "x-forwarded-for",
"description": "
HTTP header used to pass information about the client IP address.
Relevant when the EMQX cluster is deployed behind a load-balancer.
",
"type": "string"
},
"proxy_port_header": {
"default": "x-forwarded-port",
"description": "
HTTP header used to pass information about the client port.
Relevant when the EMQX cluster is deployed behind a load-balancer.
",
"type": "string"
},
"deflate_opts": {
"$ref": "#/components/schemas/broker.deflate_opts"
}
},
"type": "object"
},
"dashboard.https": {
"required": [
"bind",
"enable"
],
"properties": {
"enable": {
"default": false,
"description": "Ignore or enable this listener",
"type": "boolean"
},
"bind": {
"default": 18084,
"description": "Port without IP(18083) or port with specified IP(127.0.0.1:18083).",
"example": "0.0.0.0:18084",
"oneOf": [
{
"example": "127.0.0.1:80",
"type": "string"
},
{
"minimum": 0,
"type": "integer"
}
]
},
"num_acceptors": {
"default": 20,
"description": "Socket acceptor pool size for TCP protocols. Default is the number of schedulers online",
"type": "integer"
},
"max_connections": {
"default": 512,
"description": "Maximum number of simultaneous connections.",
"type": "integer"
},
"backlog": {
"default": 1024,
"description": "Defines the maximum length that the queue of pending connections can grow to.",
"type": "integer"
},
"send_timeout": {
"default": "10s",
"description": "Send timeout for the socket.",
"example": "12m",
"type": "string"
},
"inet6": {
"default": false,
"description": "Enable IPv6 support, default is false, which means IPv4 only.",
"type": "boolean"
},
"ipv6_v6only": {
"default": false,
"description": "Disable IPv4-to-IPv6 mapping for the listener.
The configuration is only valid when the inet6 is true.",
"type": "boolean"
},
"cacertfile": {
"description": "
Trusted PEM format CA certificates bundle file.
The certificates in this file are used to verify the TLS peer's certificates.
Append new certificates to the file if new CAs are to be trusted.
There is no need to restart EMQX to have the updated file loaded, because
the system regularly checks if file has been updated (and reload).
NOTE: invalidating (deleting) a certificate from the file will not affect
already established connections.
",
"type": "string"
},
"certfile": {
"description": "
PEM format certificates chain file.
The certificates in this file should be in reversed order of the certificate
issue chain. That is, the host's certificate should be placed in the beginning
of the file, followed by the immediate issuer certificate and so on.
Although the root CA certificate is optional, it should be placed at the end of
the file if it is to be added.
",
"type": "string"
},
"keyfile": {
"description": "PEM format private key file. ",
"type": "string"
},
"verify": {
"default": "verify_none",
"description": "Enable or disable peer verification. ",
"enum": [
"verify_peer",
"verify_none"
],
"type": "string"
},
"reuse_sessions": {
"default": true,
"description": "Enable TLS session reuse. ",
"type": "boolean"
},
"depth": {
"default": 10,
"description": "
Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path.
So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly;
if 1 the path can be PEER, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
",
"type": "integer"
},
"password": {
"description": "
String containing the user's password.
Only used if the private key file is password-protected.
",
"example": "",
"format": "password",
"type": "string"
},
"versions": {
"default": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
],
"description": "
All TLS/DTLS versions to be supported.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
In case PSK cipher suites are intended, make sure to configure
['tlsv1.2', 'tlsv1.1'] here.
",
"items": {
"type": "string"
},
"type": "array"
},
"ciphers": {
"default": "",
"description": "
This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\" or
[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"].
Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.
The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.
NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
PSK cipher suites: \"RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA\"
",
"items": {
"type": "string"
},
"type": "array"
},
"user_lookup_fun": {
"default": "emqx_tls_psk:lookup",
"description": "EMQX-internal callback that is used to lookup pre-shared key (PSK) identity. ",
"type": "string"
},
"secure_renegotiate": {
"default": true,
"description": "
SSL parameter renegotiation is a feature that allows a client and a server
to renegotiate the parameters of the SSL connection on the fly.
RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation,
you drop support for the insecure renegotiation, prone to MitM attacks.
",
"type": "boolean"
},
"dhfile": {
"description": "
Path to a file containing PEM-encoded Diffie-Hellman parameters
to be used by the server if a cipher suite using Diffie-Hellman
key exchange is negotiated. If not specified, default parameters
are used.
NOTE: The dhfile option is not supported by TLS 1.3.
",
"type": "string"
},
"honor_cipher_order": {
"default": true,
"description": "
An important security setting, it forces the cipher to be set based
on the server-specified order instead of the client-specified order,
hence enforcing the (usually more properly configured) security
ordering of the server administrator.
",
"type": "boolean"
},
"client_renegotiation": {
"default": true,
"description": "
In protocols that support client-initiated renegotiation,
the cost of resources of such an operation is higher for the server than the client.
This can act as a vector for denial of service attacks.
The SSL application already takes measures to counter-act such attempts,
but client-initiated renegotiation can be strictly disabled by setting this option to false.
The default value is true. Note that disabling renegotiation can result in
long-lived connections becoming unusable due to limits on
the number of messages the underlying cipher suite can encipher.
",
"type": "boolean"
},
"handshake_timeout": {
"default": "15s",
"description": "
Maximum time duration allowed for the handshake to complete
",
"example": "12m",
"type": "string"
}
},
"type": "object"
},
"gateway.exproto_grpc_server": {
"required": [
"bind"
],
"properties": {
"bind": {
"description": "Listening address and port for the gRPC server.",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"ssl_options": {
"description": "SSL configuration for the gRPC server.",
"$ref": "#/components/schemas/gateway.ssl_server_opts"
}
},
"type": "object"
},
"trace.log_file_detail": {
"properties": {
"node": {
"description": "Node name",
"example": "emqx@127.0.0.1",
"type": "string"
},
"size": {
"description": "file size",
"type": "integer"
},
"mtime": {
"description": "the modification and last access times of a file",
"type": "integer"
}
},
"type": "object"
},
"emqx_conf_schema.log_rotation": {
"properties": {
"enable": {
"default": true,
"description": "Enable log rotation feature.",
"type": "boolean"
},
"count": {
"default": 10,
"description": "Maximum number of log files.",
"maximum": 2048,
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"emqx_authz_api_schema.mongo_single": {
"required": [
"database",
"server",
"collection",
"type"
],
"properties": {
"enable": {
"default": true,
"description": "Set to true or false to disable this ACL provider.",
"type": "boolean"
},
"type": {
"default": "mongodb",
"description": "Backend type.",
"enum": [
"mongodb"
],
"type": "string"
},
"collection": {
"description": "`MongoDB` collection containing the authorization data.",
"type": "string"
},
"filter": {
"default": {},
"description": "
Conditional expression that defines the filter condition in the query.
Filter supports the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
",
"example": {},
"type": "object"
},
"mongo_type": {
"default": "single",
"description": "Standalone instance. Must be set to 'single' when MongoDB server is running in standalone mode.",
"enum": [
"single"
],
"type": "string"
},
"server": {
"description": "
The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The MongoDB default port 27017 is used if `[:Port]` is not specified.
",
"type": "string"
},
"w_mode": {
"default": "unsafe",
"description": "Write mode.",
"enum": [
"unsafe",
"safe"
],
"type": "string"
},
"srv_record": {
"default": false,
"description": "Use DNS SRV record.",
"type": "boolean"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"username": {
"description": "EMQX's username in the external database.",
"type": "string"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auth_source": {
"description": "Database name associated with the user's credentials.",
"type": "string"
},
"database": {
"description": "Database name.",
"type": "string"
},
"topology": {
"$ref": "#/components/schemas/emqx_connector_mongo.topology"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"emqx_authn_schema.node_metrics": {
"properties": {
"node": {
"description": "Node name.",
"example": "emqx@127.0.0.1",
"type": "string"
},
"metrics": {
"description": "The metrics of the resource.",
"$ref": "#/components/schemas/emqx_authn_schema.metrics"
}
},
"type": "object"
},
"connector-mqtt.ingress_local": {
"properties": {
"topic": {
"description": "
Send messages to which topic of the local broker.
Template with variables is allowed.
",
"type": "string"
},
"qos": {
"default": "${qos}",
"description": "
The QoS of the MQTT message to be sent.
Template with variables is allowed.
",
"oneOf": [
{
"type": "string"
},
{
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
]
},
"retain": {
"default": "${retain}",
"description": "
The 'retain' flag of the MQTT message to be sent.
Template with variables is allowed.
",
"oneOf": [
{
"type": "string"
},
{
"type": "boolean"
}
]
},
"payload": {
"description": "
The payload of the MQTT message to be sent.
Template with variables is allowed.
",
"type": "string"
}
},
"type": "object"
},
"emqx_gateway_api.dtls_listener": {
"properties": {
"id": {
"description": "Listener ID",
"type": "string"
},
"type": {
"description": "Listener Type",
"enum": [
"dtls"
],
"type": "string"
},
"name": {
"description": "Listener Name",
"type": "string"
},
"running": {
"description": "Listener Running status",
"type": "boolean"
},
"acceptors": {
"default": 16,
"description": "Size of the acceptor pool.",
"type": "integer"
},
"udp_options": {
"$ref": "#/components/schemas/gateway.udp_opts"
},
"enable": {
"default": true,
"description": "Enable the listener.",
"type": "boolean"
},
"bind": {
"description": "The IP address and port that the listener will bind.",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"max_connections": {
"default": 1024,
"description": "Maximum number of concurrent connections.",
"type": "integer"
},
"max_conn_rate": {
"default": 1000,
"description": "Maximum connections per second.",
"type": "integer"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"enable_authn": {
"default": true,
"description": "Set true (default) to enable client authentication on this listener.
When set to false clients will be allowed to connect without authentication.",
"type": "boolean"
},
"mountpoint": {
"description": "When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint` set to `some_tenant`, then the client actually subscribes to the topic `some_tenant/t`. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic `t`, the message is routed to all the clients subscribed `some_tenant/t`, so client A will receive the message, with topic name `t`. Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"access_rules": {
"default": "",
"description": "The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny",
"items": {
"type": "string"
},
"type": "array"
},
"dtls_options": {
"description": "DTLS socket options",
"$ref": "#/components/schemas/gateway.dtls_opts"
}
},
"type": "object"
},
"bridge_webhook.post": {
"required": [
"url",
"name",
"type"
],
"properties": {
"type": {
"description": "The Bridge Type",
"enum": [
"webhook"
],
"type": "string"
},
"name": {
"description": "Bridge name, used as a human-readable description of the bridge.",
"type": "string"
},
"enable": {
"default": true,
"description": "Enable or disable this bridge",
"type": "boolean"
},
"resource_opts": {
"default": {},
"description": "Resource options.",
"$ref": "#/components/schemas/bridge_webhook.creation_opts"
},
"connect_timeout": {
"default": "15s",
"description": "The timeout when connecting to the HTTP server.",
"example": "32s",
"type": "string"
},
"retry_interval": {
"deprecated": "since(\"5.0.4\")",
"example": "12m",
"type": "string"
},
"pool_type": {
"default": "random",
"description": "The type of the pool. Can be one of `random`, `hash`.",
"enum": [
"random",
"hash"
],
"type": "string"
},
"pool_size": {
"default": 8,
"description": "The pool size.",
"minimum": 1,
"type": "integer"
},
"enable_pipelining": {
"default": 100,
"description": "A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.",
"minimum": 1,
"type": "integer"
},
"request": {
"description": "Configure HTTP request parameters.",
"$ref": "#/components/schemas/connector-http.request"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
},
"url": {
"description": "
The URL of the HTTP Bridge.
Template with variables is allowed in the path, but variables cannot be used in the scheme, host,
or port part.
For example, http://localhost:9901/${topic} is allowed, but
http://${host}:9901/message or http://localhost:${port}/message
is not allowed.
",
"type": "string"
},
"direction": {
"deprecated": "since(\"5.0.12\")",
"description": "Deprecated, The direction of this bridge, MUST be 'egress'",
"enum": [
"egress"
],
"type": "string"
},
"local_topic": {
"description": "
The MQTT topic filter to be forwarded to the HTTP server. All MQTT 'PUBLISH' messages with the topic
matching the local_topic will be forwarded.
NOTE: if this bridge is used as the action of a rule (EMQX rule engine), and also local_topic is
configured, then both the data got from the rule and the MQTT messages that match local_topic
will be forwarded.
",
"type": "string"
},
"method": {
"default": "post",
"description": "
The method of the HTTP request. All the available methods are: post, put, get, delete.
Template with variables is allowed.
",
"enum": [
"post",
"put",
"get",
"delete"
],
"type": "string"
},
"headers": {
"default": {
"accept": "application/json",
"cache-control": "no-cache",
"connection": "keep-alive",
"content-type": "application/json",
"keep-alive": "timeout=5"
},
"description": "
The headers of the HTTP request.
Template with variables is allowed.
",
"example": {},
"type": "object"
},
"body": {
"description": "
The body of the HTTP request.
If not provided, the body will be a JSON object of all the available fields.
There, 'all the available fields' means the context of a MQTT message when
this webhook is triggered by receiving a MQTT message (the `local_topic` is set),
or the context of the event when this webhook is triggered by a rule (i.e. this
webhook is used as an action of a rule).
Template with variables is allowed.
",
"type": "string"
},
"max_retries": {
"default": 2,
"description": "HTTP request max retry times if failed.",
"minimum": 0,
"type": "integer"
},
"request_timeout": {
"default": "15s",
"description": "HTTP request timeout.",
"example": "32s",
"type": "string"
}
},
"type": "object"
},
"authn-builtin_db.authentication": {
"required": [
"user_id_type",
"backend",
"mechanism"
],
"properties": {
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"password_based"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"built_in_database"
],
"type": "string"
},
"user_id_type": {
"default": "username",
"description": "Specify whether to use `clientid` or `username` for authentication.",
"enum": [
"clientid",
"username"
],
"type": "string"
},
"password_hash_algorithm": {
"default": {
"name": "sha256",
"salt_position": "prefix"
},
"description": "Options for password hash creation and verification.",
"oneOf": [
{
"$ref": "#/components/schemas/authn-hash.other_algorithms"
},
{
"$ref": "#/components/schemas/authn-hash.pbkdf2"
},
{
"$ref": "#/components/schemas/authn-hash.bcrypt_rw"
}
]
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
}
},
"type": "object"
},
"dashboard.user": {
"properties": {
"username": {
"description": "Dashboard Username",
"example": "admin",
"maxLength": 100,
"type": "string"
},
"description": {
"description": "Dashboard User Description",
"example": "administrator",
"type": "string"
}
},
"type": "object"
},
"emqx_gateway_api_clients.lwm2m_client": {
"properties": {
"endpoint_name": {
"description": "The LwM2M client endpoint name",
"type": "string"
},
"lifetime": {
"description": "LwM2M Life time",
"type": "integer"
},
"node": {
"description": "Name of the node to which the client is connected",
"type": "string"
},
"clientid": {
"description": "Client ID",
"type": "string"
},
"username": {
"description": "Username of client when connecting",
"type": "string"
},
"mountpoint": {
"description": "Topic mountpoint",
"type": "string"
},
"proto_name": {
"description": "Client protocol name",
"type": "string"
},
"proto_ver": {
"description": "Protocol version used by the client",
"type": "string"
},
"ip_address": {
"description": "Client's IP address",
"type": "string"
},
"port": {
"description": "Client's port",
"type": "integer"
},
"is_bridge": {
"description": "Indicates whether the client is connected via bridge",
"type": "boolean"
},
"connected_at": {
"description": "Client connection time",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"disconnected_at": {
"description": "Client offline time, This field is only valid and returned when connected is false",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"connected": {
"description": "Whether the client is connected",
"type": "boolean"
},
"keepalive": {
"description": "Keepalive time, with the unit of second",
"type": "integer"
},
"clean_start": {
"description": "Indicate whether the client is using a brand new session",
"type": "boolean"
},
"expiry_interval": {
"description": "Session expiration interval, with the unit of second",
"type": "integer"
},
"created_at": {
"description": "Session creation time",
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"subscriptions_cnt": {
"description": "Number of subscriptions established by this client",
"type": "integer"
},
"subscriptions_max": {
"description": "Maximum number of subscriptions allowed by this client",
"type": "integer"
},
"inflight_cnt": {
"description": "Current length of inflight",
"type": "integer"
},
"inflight_max": {
"description": "Maximum length of inflight",
"type": "integer"
},
"mqueue_len": {
"description": "Current length of message queue",
"type": "integer"
},
"mqueue_max": {
"description": "Maximum length of message queue",
"type": "integer"
},
"mqueue_dropped": {
"description": "Number of messages dropped by the message queue due to exceeding the length",
"type": "integer"
},
"awaiting_rel_cnt": {
"description": "Number of awaiting acknowledge packet",
"type": "integer"
},
"awaiting_rel_max": {
"description": "Maximum allowed number of awaiting PUBREC packet",
"type": "integer"
},
"recv_oct": {
"description": "Number of bytes received",
"type": "integer"
},
"recv_cnt": {
"description": "Number of socket packets received",
"type": "integer"
},
"recv_pkt": {
"description": "Number of protocol packets received",
"type": "integer"
},
"recv_msg": {
"description": "Number of message packets received",
"type": "integer"
},
"send_oct": {
"description": "Number of bytes sent",
"type": "integer"
},
"send_cnt": {
"description": "Number of socket packets sent",
"type": "integer"
},
"send_pkt": {
"description": "Number of protocol packets sent",
"type": "integer"
},
"send_msg": {
"description": "Number of message packets sent",
"type": "integer"
},
"mailbox_len": {
"description": "Process mailbox size",
"type": "integer"
},
"heap_size": {
"description": "Process heap size with the unit of byte",
"type": "integer"
},
"reductions": {
"description": "Erlang reduction",
"type": "integer"
}
},
"type": "object"
},
"bridge_webhook.put": {
"required": [
"url"
],
"properties": {
"enable": {
"default": true,
"description": "Enable or disable this bridge",
"type": "boolean"
},
"resource_opts": {
"default": {},
"description": "Resource options.",
"$ref": "#/components/schemas/bridge_webhook.creation_opts"
},
"connect_timeout": {
"default": "15s",
"description": "The timeout when connecting to the HTTP server.",
"example": "32s",
"type": "string"
},
"retry_interval": {
"deprecated": "since(\"5.0.4\")",
"example": "12m",
"type": "string"
},
"pool_type": {
"default": "random",
"description": "The type of the pool. Can be one of `random`, `hash`.",
"enum": [
"random",
"hash"
],
"type": "string"
},
"pool_size": {
"default": 8,
"description": "The pool size.",
"minimum": 1,
"type": "integer"
},
"enable_pipelining": {
"default": 100,
"description": "A positive integer. Whether to send HTTP requests continuously, when set to 1, it means that after each HTTP request is sent, you need to wait for the server to return and then continue to send the next request.",
"minimum": 1,
"type": "integer"
},
"request": {
"description": "Configure HTTP request parameters.",
"$ref": "#/components/schemas/connector-http.request"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
},
"url": {
"description": "
The URL of the HTTP Bridge.
Template with variables is allowed in the path, but variables cannot be used in the scheme, host,
or port part.
For example, http://localhost:9901/${topic} is allowed, but
http://${host}:9901/message or http://localhost:${port}/message
is not allowed.
",
"type": "string"
},
"direction": {
"deprecated": "since(\"5.0.12\")",
"description": "Deprecated, The direction of this bridge, MUST be 'egress'",
"enum": [
"egress"
],
"type": "string"
},
"local_topic": {
"description": "
The MQTT topic filter to be forwarded to the HTTP server. All MQTT 'PUBLISH' messages with the topic
matching the local_topic will be forwarded.
NOTE: if this bridge is used as the action of a rule (EMQX rule engine), and also local_topic is
configured, then both the data got from the rule and the MQTT messages that match local_topic
will be forwarded.
",
"type": "string"
},
"method": {
"default": "post",
"description": "
The method of the HTTP request. All the available methods are: post, put, get, delete.
Template with variables is allowed.
",
"enum": [
"post",
"put",
"get",
"delete"
],
"type": "string"
},
"headers": {
"default": {
"accept": "application/json",
"cache-control": "no-cache",
"connection": "keep-alive",
"content-type": "application/json",
"keep-alive": "timeout=5"
},
"description": "
The headers of the HTTP request.
Template with variables is allowed.
",
"example": {},
"type": "object"
},
"body": {
"description": "
The body of the HTTP request.
If not provided, the body will be a JSON object of all the available fields.
There, 'all the available fields' means the context of a MQTT message when
this webhook is triggered by receiving a MQTT message (the `local_topic` is set),
or the context of the event when this webhook is triggered by a rule (i.e. this
webhook is used as an action of a rule).
Template with variables is allowed.
",
"type": "string"
},
"max_retries": {
"default": 2,
"description": "HTTP request max retry times if failed.",
"minimum": 0,
"type": "integer"
},
"request_timeout": {
"default": "15s",
"description": "HTTP request timeout.",
"example": "32s",
"type": "string"
}
},
"type": "object"
},
"limiter.bucket_opts": {
"properties": {
"rate": {
"default": "infinity",
"description": "Rate for this bucket.",
"example": "10MB",
"type": "string"
},
"capacity": {
"default": "infinity",
"description": "The capacity of this token bucket.",
"example": "100MB",
"type": "string"
},
"initial": {
"default": "0",
"description": "The initial number of tokens for this bucket.",
"example": "0MB",
"type": "string"
}
},
"type": "object"
},
"emqx_conf_schema.node": {
"required": [
"data_dir",
"cookie"
],
"properties": {
"name": {
"default": "emqx@127.0.0.1",
"description": "Unique name of the EMQX node. It must follow %name%@FQDN or
%name%@IPv4 format.
",
"readOnly": true,
"type": "string"
},
"cookie": {
"description": "Secret cookie is a random string that should be the same on all nodes in
the given EMQX cluster, but unique per EMQX cluster. It is used to prevent EMQX nodes that
belong to different clusters from accidentally connecting to each other.",
"readOnly": true,
"type": "string"
},
"process_limit": {
"default": 2097152,
"description": "Maximum number of simultaneously existing processes for this Erlang system.
The actual maximum chosen may be much larger than the Number passed.
For more information, see: https://www.erlang.org/doc/man/erl.html
",
"maximum": 134217727,
"minimum": 1024,
"readOnly": true,
"type": "integer"
},
"max_ports": {
"default": 1048576,
"description": "Maximum number of simultaneously existing ports for this Erlang system.
The actual maximum chosen may be much larger than the Number passed.
For more information, see: https://www.erlang.org/doc/man/erl.html
",
"maximum": 134217727,
"minimum": 1024,
"readOnly": true,
"type": "integer"
},
"dist_buffer_size": {
"default": 8192,
"description": "Erlang's distribution buffer busy limit in kilobytes.",
"maximum": 2097151,
"minimum": 1,
"readOnly": true,
"type": "integer"
},
"max_ets_tables": {
"default": 262144,
"description": "Max number of ETS tables",
"minimum": 1,
"readOnly": true,
"type": "integer"
},
"data_dir": {
"description": "
Path to the persistent data directory.
Possible auto-created subdirectories are:
- `mnesia/`: EMQX's built-in database directory.
For example, `mnesia/emqx@127.0.0.1`.
There should be only one such subdirectory.
Meaning, in case the node is to be renamed (to e.g. `emqx@10.0.1.1`),
the old dir should be deleted first.
- `configs`: Generated configs at boot time, and cluster/local override configs.
- `patches`: Hot-patch beam files are to be placed here.
- `trace`: Trace log files.
**NOTE**: One data dir cannot be shared by two or more EMQX nodes.
",
"readOnly": true,
"type": "string"
},
"config_files": {
"items": {
"type": "string"
},
"readOnly": true,
"type": "array"
},
"global_gc_interval": {
"default": "15m",
"description": "Periodic garbage collection interval. Set to disabled to have it disabled.",
"readOnly": true,
"oneOf": [
{
"example": "12m",
"type": "string"
},
{
"enum": [
"disabled"
],
"type": "string"
}
]
},
"crash_dump_file": {
"default": "log/erl_crash.dump",
"description": "Location of the crash dump file.",
"example": "/path/to/file",
"readOnly": true,
"type": "string"
},
"crash_dump_seconds": {
"default": "30s",
"description": "This variable gives the number of seconds that the emulator is allowed to spend writing a crash dump. When the given number of seconds have elapsed, the emulator is terminated.
- If setting to 0 seconds, the runtime system does not even attempt to write the crash dump file. It only terminates.
- If setting to a positive value S, wait for S seconds to complete the crash dump file and then terminates the runtime system with a SIGALRM signal.
- A negative value causes the termination of the runtime system to wait indefinitely until the crash dump file has been completely written.
",
"example": "1h",
"readOnly": true,
"type": "string"
},
"crash_dump_bytes": {
"default": "100MB",
"description": "This variable sets the maximum size of a crash dump file in bytes.
The crash dump will be truncated if this limit is exceeded.
If setting it to 0, the runtime system does not even attempt to write a crash dump file.
",
"example": "32MB",
"readOnly": true,
"type": "string"
},
"dist_net_ticktime": {
"default": "2m",
"description": "This is the approximate time an EMQX node may be unresponsive until it is considered down and thereby disconnected.",
"example": "1h",
"readOnly": true,
"type": "string"
},
"backtrace_depth": {
"default": 23,
"description": "Maximum depth of the call stack printed in error messages and
process_info.
",
"readOnly": true,
"type": "integer"
},
"applications": {
"default": "",
"description": "List of Erlang applications that shall be rebooted when the EMQX broker joins the cluster.
",
"example": "item1,item2",
"readOnly": true,
"type": "string"
},
"etc_dir": {
"deprecated": "since(\"5.0.8\")",
"description": "etc dir for the node",
"readOnly": true,
"type": "string"
},
"cluster_call": {
"readOnly": true,
"$ref": "#/components/schemas/emqx_conf_schema.cluster_call"
},
"db_backend": {
"default": "rlog",
"description": "
Select the backend for the embedded database.
rlog is the default backend,
that is suitable for very large clusters.
mnesia is a backend that offers decent performance in small clusters.
",
"enum": [
"mnesia",
"rlog"
],
"readOnly": true,
"type": "string"
},
"db_role": {
"default": "core",
"description": "
Select a node role.
core nodes provide durability of the data, and take care of writes.
It is recommended to place core nodes in different racks or different availability zones.
replicant nodes are ephemeral worker nodes. Removing them from the cluster
doesn't affect database redundancy
It is recommended to have more replicant nodes than core nodes.
Note: this parameter only takes effect when the backend is set
to rlog.
",
"enum": [
"core",
"replicant"
],
"readOnly": true,
"type": "string"
},
"rpc_module": {
"default": "gen_rpc",
"description": "Protocol used for pushing transaction logs to the replicant nodes.",
"enum": [
"gen_rpc",
"rpc"
],
"readOnly": true,
"type": "string"
},
"tlog_push_mode": {
"default": "async",
"description": "
In sync mode the core node waits for an ack from the replicant nodes before sending the next
transaction log entry.
",
"enum": [
"sync",
"async"
],
"readOnly": true,
"type": "string"
},
"default_shard_transport": {
"default": "gen_rpc",
"description": "Defines the default transport for pushing transaction logs.
This may be overridden on a per-shard basis in db.shard_transports.
gen_rpc uses the gen_rpc library,
distr uses the Erlang distribution.
",
"enum": [
"gen_rpc",
"distr"
],
"type": "string"
},
"shard_transports": {
"default": {},
"description": "Allows to tune the transport method used for transaction log replication, on a per-shard basis.
gen_rpc uses the gen_rpc library,
distr uses the Erlang distribution.
If not specified,
the default is to use the value set in db.default_shard_transport.",
"properties": {
"$shard": {
"enum": [
"gen_rpc",
"distr"
],
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"auto_subscribe.topic": {
"required": [
"topic"
],
"properties": {
"topic": {
"description": "Topic name, placeholders are supported. For example: client/${clientid}/username/${username}/host/${host}/port/${port}
Required field, and cannot be empty string",
"example": "/clientid/${clientid}/username/${username}/host/${host}/port/${port}",
"type": "string"
},
"qos": {
"default": 0,
"description": "Default value 0. Quality of service.
At most once (0)
At least once (1)
Exactly once (2)",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
},
"rh": {
"default": 0,
"description": "Default value 0. This option is used to specify whether the server forwards the retained message to the client when establishing a subscription.
Retain Handling is equal to 0, as long as the client successfully subscribes, the server will send the retained message.
Retain Handling is equal to 1, if the client successfully subscribes and this subscription does not exist previously, the server sends the retained message. After all, sometimes the client re-initiate the subscription just to change the QoS, but it does not mean that it wants to receive the reserved messages again.
Retain Handling is equal to 2, even if the client successfully subscribes, the server does not send the retained message.",
"maximum": 2,
"minimum": 0,
"type": "integer"
},
"rap": {
"default": 0,
"description": "Default value 0. This option is used to specify whether the server retains the RETAIN mark when forwarding messages to the client, and this option does not affect the RETAIN mark in the retained message. Therefore, when the option Retain As Publish is set to 0, the client will directly distinguish whether this is a normal forwarded message or a retained message according to the RETAIN mark in the message, instead of judging whether this message is the first received after subscribing(the forwarded message may be sent before the retained message, which depends on the specific implementation of different brokers).",
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"nl": {
"default": 0,
"description": "Default value 0.
MQTT v3.1.1： if you subscribe to the topic published by yourself, you will receive all messages that you published.
MQTT v5: if you set this option as 1 when subscribing, the server will not forward the message you published to you.",
"maximum": 1,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"broker.listener_ssl_opts": {
"properties": {
"cacertfile": {
"description": "
Trusted PEM format CA certificates bundle file.
The certificates in this file are used to verify the TLS peer's certificates.
Append new certificates to the file if new CAs are to be trusted.
There is no need to restart EMQX to have the updated file loaded, because
the system regularly checks if file has been updated (and reload).
NOTE: invalidating (deleting) a certificate from the file will not affect
already established connections.
",
"type": "string"
},
"certfile": {
"description": "
PEM format certificates chain file.
The certificates in this file should be in reversed order of the certificate
issue chain. That is, the host's certificate should be placed in the beginning
of the file, followed by the immediate issuer certificate and so on.
Although the root CA certificate is optional, it should be placed at the end of
the file if it is to be added.
",
"type": "string"
},
"keyfile": {
"description": "PEM format private key file. ",
"type": "string"
},
"verify": {
"default": "verify_none",
"description": "Enable or disable peer verification. ",
"enum": [
"verify_peer",
"verify_none"
],
"type": "string"
},
"reuse_sessions": {
"default": true,
"description": "Enable TLS session reuse. ",
"type": "boolean"
},
"depth": {
"default": 10,
"description": "
Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path.
So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly;
if 1 the path can be PEER, Intermediate-CA, ROOT-CA;
if 2 the path can be PEER, Intermediate-CA1, Intermediate-CA2, ROOT-CA.
",
"type": "integer"
},
"password": {
"description": "
String containing the user's password.
Only used if the private key file is password-protected.
",
"example": "",
"format": "password",
"type": "string"
},
"versions": {
"default": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
],
"description": "
All TLS/DTLS versions to be supported.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config.
In case PSK cipher suites are intended, make sure to configure
['tlsv1.2', 'tlsv1.1'] here.
",
"items": {
"type": "string"
},
"type": "array"
},
"ciphers": {
"default": "",
"description": "
This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\" or
[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"].
Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.
The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.
NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
PSK cipher suites: \"RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA\"
",
"items": {
"type": "string"
},
"type": "array"
},
"user_lookup_fun": {
"default": "emqx_tls_psk:lookup",
"description": "EMQX-internal callback that is used to lookup pre-shared key (PSK) identity. ",
"type": "string"
},
"secure_renegotiate": {
"default": true,
"description": "
SSL parameter renegotiation is a feature that allows a client and a server
to renegotiate the parameters of the SSL connection on the fly.
RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation,
you drop support for the insecure renegotiation, prone to MitM attacks.
",
"type": "boolean"
},
"dhfile": {
"description": "
Path to a file containing PEM-encoded Diffie-Hellman parameters
to be used by the server if a cipher suite using Diffie-Hellman
key exchange is negotiated. If not specified, default parameters
are used.
NOTE: The dhfile option is not supported by TLS 1.3.
",
"type": "string"
},
"fail_if_no_peer_cert": {
"default": false,
"description": "
Used together with {verify, verify_peer} by an TLS/DTLS server.
If set to true, the server fails if the client does not have a
certificate to send, that is, sends an empty certificate.
If set to false, it fails only if the client sends an invalid
certificate (an empty certificate is considered valid).
",
"type": "boolean"
},
"honor_cipher_order": {
"default": true,
"description": "
An important security setting, it forces the cipher to be set based
on the server-specified order instead of the client-specified order,
hence enforcing the (usually more properly configured) security
ordering of the server administrator.
",
"type": "boolean"
},
"client_renegotiation": {
"default": true,
"description": "
In protocols that support client-initiated renegotiation,
the cost of resources of such an operation is higher for the server than the client.
This can act as a vector for denial of service attacks.
The SSL application already takes measures to counter-act such attempts,
but client-initiated renegotiation can be strictly disabled by setting this option to false.
The default value is true. Note that disabling renegotiation can result in
long-lived connections becoming unusable due to limits on
the number of messages the underlying cipher suite can encipher.
",
"type": "boolean"
},
"handshake_timeout": {
"default": "15s",
"description": "
Maximum time duration allowed for the handshake to complete
",
"example": "12m",
"type": "string"
},
"gc_after_handshake": {
"default": false,
"description": "
Memory usage tuning. If enabled, will immediately perform a garbage collection after
the TLS/SSL handshake.
",
"type": "boolean"
}
},
"type": "object"
},
"gateway.mqttsn_predefined": {
"required": [
"topic",
"id"
],
"properties": {
"id": {
"description": "Topic ID. Range: 1-65535",
"type": "integer"
},
"topic": {
"description": "Topic Name",
"type": "string"
}
},
"type": "object"
},
"emqx_gateway_api.exproto": {
"required": [
"handler",
"server"
],
"properties": {
"name": {
"description": "Gateway Name",
"enum": [
"exproto"
],
"type": "string"
},
"server": {
"description": "Configurations for starting the ConnectionAdapter service",
"$ref": "#/components/schemas/gateway.exproto_grpc_server"
},
"handler": {
"description": "Configurations for request to ConnectionHandler service",
"$ref": "#/components/schemas/gateway.exproto_grpc_handler"
},
"mountpoint": {
"default": "",
"description": " ",
"type": "string"
},
"enable": {
"default": true,
"description": "Whether to enable this gateway",
"type": "boolean"
},
"enable_stats": {
"default": true,
"description": "Whether to enable client process statistic",
"type": "boolean"
},
"idle_timeout": {
"default": "30s",
"description": "The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.",
"example": "12m",
"type": "string"
},
"clientinfo_override": {
"description": "ClientInfo override.",
"$ref": "#/components/schemas/gateway.clientinfo_override"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"listeners": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.dtls_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.udp_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.ssl_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.tcp_listener"
}
]
},
"type": "array"
}
},
"type": "object"
},
"rule_engine.user_provided_function": {
"required": [
"function"
],
"properties": {
"function": {
"description": "
The user provided function. Should be in the format: '{module}:{function}'.
Where {module} is the Erlang callback module and {function} is the Erlang function.
To write your own function, checkout the function console and
republish in the source file:
apps/emqx_rule_engine/src/emqx_rule_actions.erl as an example.
",
"example": "module:function",
"type": "string"
},
"args": {
"default": {},
"description": "
The args will be passed as the 3rd argument to module:function/3,
checkout the function console and republish in the source file:
apps/emqx_rule_engine/src/emqx_rule_actions.erl as an example.
",
"example": {},
"type": "object"
}
},
"type": "object"
},
"emqx_authn_schema.node_resource_metrics": {
"properties": {
"node": {
"description": "Node name.",
"example": "emqx@127.0.0.1",
"type": "string"
},
"metrics": {
"description": "The metrics of the resource.",
"$ref": "#/components/schemas/emqx_authn_schema.resource_metrics"
}
},
"type": "object"
},
"listeners.quic_required_bind(with_name)": {
"required": [
"bind",
"name",
"type"
],
"properties": {
"type": {
"description": "Listener type",
"enum": [
"quic"
],
"type": "string"
},
"running": {
"description": "Listener status",
"type": "boolean"
},
"name": {
"description": "Listener name",
"type": "string"
},
"current_connections": {
"description": "Current connections",
"minimum": 0,
"type": "integer"
},
"certfile": {
"description": "Path to the certificate file.",
"type": "string"
},
"keyfile": {
"description": "Path to the secret key file. ",
"type": "string"
},
"ciphers": {
"default": [
"TLS_AES_256_GCM_SHA384",
"TLS_AES_128_GCM_SHA256",
"TLS_CHACHA20_POLY1305_SHA256"
],
"description": "
This config holds TLS cipher suite names separated by comma,
or as an array of strings. e.g.
\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\" or
[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"].
Ciphers (and their ordering) define the way in which the
client and server encrypts information over the network connection.
Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance.
The names should be in OpenSSL string format (not RFC format).
All default values and examples provided by EMQX config
documentation are all in OpenSSL format.
NOTE: Certain cipher suites are only compatible with
specific TLS versions ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the versions,
configuring cipher suites for other versions will have no effect.
NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config
If PSK cipher suites are intended, 'tlsv1.3' should be disabled from versions.
PSK cipher suites: \"RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,
RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,
RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,
RSA-PSK-DES-CBC3-SHA,RSA-PSK-RC4-SHA\"
NOTE: QUIC listener supports only 'tlsv1.3' ciphers
",
"items": {
"type": "string"
},
"type": "array"
},
"idle_timeout": {
"default": 0,
"description": "How long a connection can go idle before it is gracefully shut down. 0 to disable",
"example": "32s",
"type": "string"
},
"handshake_idle_timeout": {
"default": "10s",
"description": "How long a handshake can idle before it is discarded. ",
"example": "32s",
"type": "string"
},
"keep_alive_interval": {
"default": 0,
"description": "
How often to send PING frames to keep a connection alive. 0 means disabled.
",
"example": "32s",
"type": "string"
},
"enabled": {
"default": true,
"description": "Enable listener. ",
"type": "boolean"
},
"bind": {
"default": 14567,
"description": "
IP address and port for the listening socket.
",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"acceptors": {
"default": 16,
"description": "The size of the listener's receiving pool.",
"minimum": 1,
"type": "integer"
},
"max_connections": {
"default": "infinity",
"description": "The maximum number of concurrent connections allowed by the listener. ",
"oneOf": [
{
"minimum": 1,
"type": "integer"
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"mountpoint": {
"default": "",
"description": "
When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message
is delivered to the subscriber. The mountpoint is a way that users can use
to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint`
set to `some_tenant`, then the client actually subscribes to the topic
`some_tenant/t`. Similarly, if another client B (connected to the same listener
as the client A) sends a message to topic `t`, the message is routed
to all the clients subscribed `some_tenant/t`, so client A will receive the
message, with topic name `t`.
Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"zone": {
"default": "default",
"description": "
The configuration zone to which the listener belongs.
",
"type": "string"
},
"limiter": {
"default": {
"connection": {
"capacity": 1000,
"rate": "1000/s"
}
},
"description": "
Type of the rate limit.
",
"$ref": "#/components/schemas/limiter.listener_fields"
},
"enable_authn": {
"default": true,
"description": "
Set true (default) to enable client authentication on this listener, the authentication
process goes through the configured authentication chain.
When set to false to allow any clients with or without authentication information such as username or password to log in.
When set to quick_deny_anonymous, it behaves like when set to true, but clients will be
denied immediately without going through any authenticators if username is not provided. This is useful to fence off
anonymous clients early.
",
"enum": [
true,
false,
"quick_deny_anonymous"
],
"type": "string"
}
},
"type": "object"
},
"emqx_gateway_api.udp_listener": {
"properties": {
"id": {
"description": "Listener ID",
"type": "string"
},
"type": {
"description": "Listener Type",
"enum": [
"udp"
],
"type": "string"
},
"name": {
"description": "Listener Name",
"type": "string"
},
"running": {
"description": "Listener Running status",
"type": "boolean"
},
"udp_options": {
"$ref": "#/components/schemas/gateway.udp_opts"
},
"enable": {
"default": true,
"description": "Enable the listener.",
"type": "boolean"
},
"bind": {
"description": "The IP address and port that the listener will bind.",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"max_connections": {
"default": 1024,
"description": "Maximum number of concurrent connections.",
"type": "integer"
},
"max_conn_rate": {
"default": 1000,
"description": "Maximum connections per second.",
"type": "integer"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"enable_authn": {
"default": true,
"description": "Set true (default) to enable client authentication on this listener.
When set to false clients will be allowed to connect without authentication.",
"type": "boolean"
},
"mountpoint": {
"description": "When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint` set to `some_tenant`, then the client actually subscribes to the topic `some_tenant/t`. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic `t`, the message is routed to all the clients subscribed `some_tenant/t`, so client A will receive the message, with topic name `t`. Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"access_rules": {
"default": "",
"description": "The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"emqx_gateway_api_listeners.tcp_listener": {
"properties": {
"id": {
"description": "Listener ID",
"type": "string"
},
"type": {
"description": "Listener Type",
"enum": [
"tcp"
],
"type": "string"
},
"name": {
"description": "Listener Name",
"type": "string"
},
"running": {
"description": "Listener Running status",
"type": "boolean"
},
"acceptors": {
"default": 16,
"description": "Size of the acceptor pool.",
"type": "integer"
},
"tcp_options": {
"description": "Setting the TCP socket options.",
"$ref": "#/components/schemas/broker.tcp_opts"
},
"proxy_protocol": {
"default": false,
"description": "Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx.
See: https://www.haproxy.com/blog/haproxy/proxy-protocol/",
"type": "boolean"
},
"proxy_protocol_timeout": {
"default": "15s",
"description": "Timeout for proxy protocol.
EMQX will close the TCP connection if proxy protocol packet is not received within the timeout.",
"example": "12m",
"type": "string"
},
"enable": {
"default": true,
"description": "Enable the listener.",
"type": "boolean"
},
"bind": {
"description": "The IP address and port that the listener will bind.",
"oneOf": [
{
"type": "integer"
},
{
"example": "127.0.0.1:80",
"type": "string"
}
]
},
"max_connections": {
"default": 1024,
"description": "Maximum number of concurrent connections.",
"type": "integer"
},
"max_conn_rate": {
"default": 1000,
"description": "Maximum connections per second.",
"type": "integer"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"enable_authn": {
"default": true,
"description": "Set true (default) to enable client authentication on this listener.
When set to false clients will be allowed to connect without authentication.",
"type": "boolean"
},
"mountpoint": {
"description": "When publishing or subscribing, prefix all topics with a mountpoint string.
The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
For example if a client A subscribes to `t` with `listeners.tcp.\\.mountpoint` set to `some_tenant`, then the client actually subscribes to the topic `some_tenant/t`. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic `t`, the message is routed to all the clients subscribed `some_tenant/t`, so client A will receive the message, with topic name `t`. Set to `\"\"` to disable the feature.
Variables in mountpoint string:
- ${clientid}: clientid
- ${username}: username
",
"type": "string"
},
"access_rules": {
"default": "",
"description": "The access control rules for this listener.
See: https://github.com/emqtt/esockd#allowdeny",
"items": {
"type": "string"
},
"type": "array"
},
"status": {
"description": "listener status ",
"$ref": "#/components/schemas/listeners.status"
},
"node_status": {
"description": "listener status of each node in the cluster",
"items": {
"$ref": "#/components/schemas/listeners.node_status"
},
"type": "array"
}
},
"type": "object"
},
"emqx_delayed_api.message": {
"properties": {
"msgid": {
"description": "Delayed Message ID",
"type": "integer"
},
"node": {
"description": "The node where message from",
"type": "string"
},
"publish_at": {
"description": "Clinet publish message time, in RFC 3339 format",
"type": "string"
},
"delayed_interval": {
"description": "Delayed interval(second)",
"minimum": 1,
"type": "integer"
},
"delayed_remaining": {
"description": "Delayed remaining(second)",
"minimum": 0,
"type": "integer"
},
"expected_at": {
"description": "Expect publish time, in RFC 3339 format",
"type": "string"
},
"topic": {
"description": "Topic",
"example": "/sys/#",
"type": "string"
},
"qos": {
"description": "QoS",
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
},
"from_clientid": {
"description": "From ClientID",
"type": "string"
},
"from_username": {
"description": "From Username",
"type": "string"
},
"payload": {
"description": "Payload, base64 encoded. Payload will be set to 'PAYLOAD_TO_LARGE' if its length is larger than 2048 bytes",
"type": "string"
}
},
"type": "object"
},
"broker.persistent_table_mria_opts": {
"properties": {
"ram_cache": {
"default": true,
"description": "Maintain a copy of the data in RAM for faster access.",
"type": "boolean"
}
},
"type": "object"
},
"authn-hash.pbkdf2": {
"required": [
"iterations",
"mac_fun",
"name"
],
"properties": {
"name": {
"description": "PBKDF2 password hashing.",
"enum": [
"pbkdf2"
],
"type": "string"
},
"mac_fun": {
"description": "Specifies mac_fun for PBKDF2 hashing algorithm.",
"enum": [
"md4",
"md5",
"ripemd160",
"sha",
"sha224",
"sha256",
"sha384",
"sha512"
],
"type": "string"
},
"iterations": {
"description": "Iteration count for PBKDF2 hashing algorithm.",
"type": "integer"
},
"dk_length": {
"description": "Derived length for PBKDF2 hashing algorithm. If not specified, calculated automatically based on `mac_fun`.",
"type": "integer"
}
},
"type": "object"
},
"emqx_mgmt_api_publish.message_properties": {
"properties": {
"payload_format_indicator": {
"description": "0 (0x00) Byte Indicates that the Payload is unspecified bytes, which is equivalent to not sending a Payload Format Indicator.
1 (0x01) Byte Indicates that the Payload is UTF-8 Encoded Character Data. The UTF-8 data in the Payload MUST be well-formed UTF-8 as defined by the Unicode specification and restated in RFC 3629.
",
"example": 0,
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"message_expiry_interval": {
"description": "Identifier of the Message Expiry Interval. If the Message Expiry Interval has passed and the Server has not managed to start onward delivery to a matching subscriber, then it MUST delete the copy of the message for that subscriber.",
"type": "integer"
},
"response_topic": {
"description": "Identifier of the Response Topic.The Response Topic MUST be a UTF-8 Encoded, It MUST NOT contain wildcard characters.",
"example": "some_other_topic",
"type": "string"
},
"correlation_data": {
"description": "Identifier of the Correlation Data. The Server MUST send the Correlation Data unaltered to all subscribers receiving the Application Message.",
"type": "string"
},
"user_properties": {
"description": "The User-Property key-value pairs. Note: in case there are duplicated keys, only the last one will be used.",
"example": {
"foo": "bar"
},
"type": "object"
},
"content_type": {
"description": "The Content Type MUST be a UTF-8 Encoded String.",
"example": "text/plain",
"type": "string"
}
},
"type": "object"
},
"limiter.client_opts": {
"properties": {
"rate": {
"default": "infinity",
"description": "Rate for this bucket.",
"example": "10MB",
"type": "string"
},
"initial": {
"default": "0",
"description": "The initial number of tokens for this bucket.",
"example": "0MB",
"type": "string"
},
"low_watermark": {
"default": "0",
"description": "If the remaining tokens are lower than this value,
the check/consume will succeed, but it will be forced to wait for a short period of time.",
"example": "0MB",
"type": "string"
},
"capacity": {
"default": "infinity",
"description": "The capacity of per user.",
"example": "100MB",
"type": "string"
},
"divisible": {
"default": false,
"description": "Is it possible to split the number of requested tokens?",
"type": "boolean"
},
"max_retry_time": {
"default": "10s",
"description": "The maximum retry time when acquire failed.",
"example": "12m",
"type": "string"
},
"failure_strategy": {
"default": "force",
"description": "The strategy when all the retries failed.",
"example": "force",
"type": "string"
}
},
"type": "object"
},
"authn-mongodb.sharded-cluster": {
"required": [
"database",
"servers",
"collection",
"backend",
"mechanism"
],
"properties": {
"mechanism": {
"description": "Authentication mechanism.",
"enum": [
"password_based"
],
"type": "string"
},
"backend": {
"description": "Backend type.",
"enum": [
"mongodb"
],
"type": "string"
},
"collection": {
"description": "Collection used to store authentication data.",
"type": "string"
},
"filter": {
"default": {},
"description": "
Conditional expression that defines the filter condition in the query.
Filter supports the following placeholders:
- ${username}: Will be replaced at runtime with Username used by the client when connecting
- ${clientid}: Will be replaced at runtime with Client ID used by the client when connecting
",
"example": {},
"type": "object"
},
"password_hash_field": {
"default": "password_hash",
"description": "Document field that contains password hash.",
"type": "string"
},
"salt_field": {
"default": "salt",
"description": "Document field that contains the password salt.",
"type": "string"
},
"is_superuser_field": {
"default": "is_superuser",
"description": "Document field that defines if the user has superuser privileges.",
"type": "string"
},
"password_hash_algorithm": {
"default": {
"name": "sha256",
"salt_position": "prefix"
},
"description": "Options for password hash verification.",
"oneOf": [
{
"$ref": "#/components/schemas/authn-hash.other_algorithms"
},
{
"$ref": "#/components/schemas/authn-hash.pbkdf2"
},
{
"$ref": "#/components/schemas/authn-hash.bcrypt"
}
]
},
"enable": {
"default": true,
"description": "Set to true or false to disable this auth provider.",
"type": "boolean"
},
"mongo_type": {
"default": "sharded",
"description": "Sharded cluster. Must be set to 'sharded' when MongoDB server is running in 'sharded' mode.",
"enum": [
"sharded"
],
"type": "string"
},
"servers": {
"description": "
A Node list for Cluster to connect to. The nodes should be separated with commas, such as: `Node[,Node].`
For each Node should be: The IPv4 or IPv6 address or the hostname to connect to.
A host entry has the following form: `Host[:Port]`.
The MongoDB default port 27017 is used if `[:Port]` is not specified.
",
"type": "string"
},
"w_mode": {
"default": "unsafe",
"description": "Write mode.",
"enum": [
"unsafe",
"safe"
],
"type": "string"
},
"srv_record": {
"default": false,
"description": "Use DNS SRV record.",
"type": "boolean"
},
"pool_size": {
"default": 8,
"description": "Size of the connection pool towards the bridge target service.",
"minimum": 1,
"type": "integer"
},
"username": {
"description": "EMQX's username in the external database.",
"type": "string"
},
"password": {
"description": "EMQX's password in the external database.",
"format": "password",
"type": "string"
},
"auth_source": {
"description": "Database name associated with the user's credentials.",
"type": "string"
},
"database": {
"description": "Database name.",
"type": "string"
},
"topology": {
"$ref": "#/components/schemas/emqx_connector_mongo.topology"
},
"ssl": {
"default": {
"enable": false
},
"description": "SSL connection settings.",
"$ref": "#/components/schemas/broker.ssl_client_opts"
}
},
"type": "object"
},
"emqx_gateway_api.gateway_overview": {
"properties": {
"name": {
"description": "Gateway Name",
"type": "string"
},
"status": {
"description": "Gateway status",
"enum": [
"running",
"stopped",
"unloaded"
],
"type": "string"
},
"created_at": {
"description": "The Gateway created datetime",
"type": "string"
},
"started_at": {
"description": "The Gateway started datetime",
"type": "string"
},
"stopped_at": {
"description": "The Gateway stopped datetime",
"type": "string"
},
"max_connections": {
"description": "The Gateway allowed maximum connections/clients",
"minimum": 1,
"type": "integer"
},
"current_connections": {
"description": "The Gateway current connected connections/clients",
"minimum": 0,
"type": "integer"
},
"listeners": {
"description": "The Gateway listeners overview",
"items": {
"$ref": "#/components/schemas/emqx_gateway_api.gateway_listener_overview"
},
"type": "array"
},
"node_status": {
"description": "The status of the gateway on each node in the cluster",
"items": {
"$ref": "#/components/schemas/emqx_gateway_api.gateway_node_status"
},
"type": "array"
}
},
"type": "object"
},
"dashboard.dashboard": {
"required": [
"default_password",
"default_username"
],
"properties": {
"listeners": {
"description": "HTTP(s) listeners are identified by their protocol type and are
used to serve dashboard UI and restful HTTP API.
Listeners must have a unique combination of port number and IP address.
For example, an HTTP listener can listen on all configured IP addresses
on a given port for a machine by specifying the IP address 0.0.0.0.
Alternatively, the HTTP listener can specify a unique IP address for each listener,
but use the same port.",
"$ref": "#/components/schemas/dashboard.listeners"
},
"default_username": {
"default": "admin",
"description": "The default username of the automatically created dashboard user.",
"readOnly": true,
"type": "string"
},
"default_password": {
"default": "public",
"description": "The initial default password for dashboard 'admin' user.
For safety, it should be changed as soon as possible.
This value is not valid when you log in to Dashboard for the first time via the web
and change to a complex password as prompted.
",
"readOnly": true,
"type": "string"
},
"sample_interval": {
"default": "10s",
"description": "How often to update metrics displayed in the dashboard.
Note: `sample_interval` should be a divisor of 60, default is 10s.",
"example": "1h",
"type": "string"
},
"token_expired_time": {
"default": "60m",
"description": "JWT token expiration time. Default is 60 minutes",
"example": "12m",
"type": "string"
},
"cors": {
"default": false,
"description": "Support Cross-Origin Resource Sharing (CORS).
Allows a server to indicate any origins (domain, scheme, or port) other than
its own from which a browser should permit loading resources.",
"type": "boolean"
},
"i18n_lang": {
"default": "en",
"description": "Internationalization language support.",
"enum": [
"en",
"zh"
],
"readOnly": true,
"type": "string"
},
"bootstrap_users_file": {
"default": "",
"description": "Deprecated, use api_key.bootstrap_file.",
"type": "string"
}
},
"type": "object"
},
"broker.sys_topics": {
"properties": {
"sys_msg_interval": {
"default": "1m",
"description": "Time interval of publishing `$SYS` messages.",
"oneOf": [
{
"example": "12m",
"type": "string"
},
{
"enum": [
"disabled"
],
"type": "string"
}
]
},
"sys_heartbeat_interval": {
"default": "30s",
"description": "Time interval for publishing following heartbeat messages:
- `$SYS/brokers//uptime`
- `$SYS/brokers//datetime`
",
"oneOf": [
{
"example": "12m",
"type": "string"
},
{
"enum": [
"disabled"
],
"type": "string"
}
]
},
"sys_event_messages": {
"description": "Client events messages.",
"$ref": "#/components/schemas/broker.event_names"
}
},
"type": "object"
},
"authz.node_resource_metrics": {
"properties": {
"node": {
"description": "Node name.",
"example": "emqx@127.0.0.1",
"type": "string"
},
"metrics": {
"description": "The metrics of the resource.",
"$ref": "#/components/schemas/authz.resource_metrics"
}
},
"type": "object"
},
"emqx_gateway_api.gateway_node_status": {
"properties": {
"node": {
"description": "Node Name",
"enum": [
"emqx@127.0.0.1"
],
"type": "string"
},
"status": {
"description": "Gateway status",
"enum": [
"running",
"stopped",
"unloaded"
],
"type": "string"
},
"max_connections": {
"description": "The Gateway allowed maximum connections/clients",
"minimum": 1,
"type": "integer"
},
"current_connections": {
"description": "The Gateway current connected connections/clients",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"emqx_gateway_api.lwm2m": {
"required": [
"translators",
"xml_dir"
],
"properties": {
"name": {
"description": "Gateway Name",
"enum": [
"lwm2m"
],
"type": "string"
},
"xml_dir": {
"description": "The Directory for LwM2M Resource definition.",
"example": "/etc/emqx/lwm2m_xml",
"type": "string"
},
"lifetime_min": {
"default": "15s",
"description": "Minimum value of lifetime allowed to be set by the LwM2M client.",
"example": "12m",
"type": "string"
},
"lifetime_max": {
"default": "86400s",
"description": "Maximum value of lifetime allowed to be set by the LwM2M client.",
"example": "12m",
"type": "string"
},
"qmode_time_window": {
"default": "22s",
"description": "The value of the time window during which the network link is considered valid by the LwM2M Gateway in QMode mode.
For example, after receiving an update message from a client, any messages within this time window are sent directly to the LwM2M client, and all messages beyond this time window are temporarily stored in memory.",
"example": "1h",
"type": "string"
},
"auto_observe": {
"default": false,
"description": "Automatically observe the object list of REGISTER packet.",
"type": "boolean"
},
"update_msg_publish_condition": {
"default": "contains_object_list",
"description": "Policy for publishing UPDATE event message.
- always: send update events as long as the UPDATE request is received.
- contains_object_list: send update events only if the UPDATE request carries any Object List
",
"enum": [
"always",
"contains_object_list"
],
"type": "string"
},
"translators": {
"description": "Topic configuration for LwM2M's gateway publishing and subscription.",
"$ref": "#/components/schemas/gateway.lwm2m_translators"
},
"mountpoint": {
"default": "lwm2m/${endpoint_name}/",
"description": " ",
"type": "string"
},
"enable": {
"default": true,
"description": "Whether to enable this gateway",
"type": "boolean"
},
"enable_stats": {
"default": true,
"description": "Whether to enable client process statistic",
"type": "boolean"
},
"idle_timeout": {
"default": "30s",
"description": "The idle time of the client connection process. It has two purposes:
1. A newly created client process that does not receive any client requests after that time will be closed directly.
2. A running client process that does not receive any client requests after this time will go into hibernation to save resources.",
"example": "12m",
"type": "string"
},
"clientinfo_override": {
"description": "ClientInfo override.",
"$ref": "#/components/schemas/gateway.clientinfo_override"
},
"authentication": {
"description": "Default authentication configs for all the gateway listeners. For per-listener overrides see authentication
in listener configs",
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"listeners": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.dtls_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.udp_listener"
}
]
},
"type": "array"
}
},
"type": "object"
},
"zone.force_shutdown": {
"properties": {
"enable": {
"description": "Enable `force_shutdown` feature.",
"type": "boolean"
},
"max_message_queue_len": {
"description": "Maximum message queue length.",
"minimum": 0,
"type": "integer"
},
"max_heap_size": {
"description": "Total heap size",
"example": "1024KB",
"type": "string"
}
},
"type": "object"
}
},
"securitySchemes": {
"basicAuth": {
"description": "Authorize with [API Keys](https://www.emqx.io/docs/en/v5.0/admin/api.html#api-keys)",
"scheme": "basic",
"type": "http"
}
}
},
"info": {
"title": "EMQX API",
"version": "5.0"
},
"openapi": "3.0.0",
"paths": {
"/authentication/{id}/position/{position}": {
"put": {
"description": "Move authenticator in global authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Position of authenticator in chain. Possible values are 'front', 'rear', 'before:{other_authenticator}', 'after:{other_authenticator}'.",
"example": "before:password_based:built_in_database",
"in": "path",
"name": "position",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Authenticator moved"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
}
},
"/metrics": {
"get": {
"description": "EMQX metrics",
"parameters": [
{
"description": "Whether to aggregate all nodes Metrics",
"in": "query",
"name": "aggregate",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_metrics.node_metrics"
},
"type": "array"
},
{
"$ref": "#/components/schemas/emqx_mgmt_api_metrics.aggregated_metrics"
}
]
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Metrics"
]
}
},
"/authentication/{id}/users/{user_id}": {
"delete": {
"description": "Delete user in authenticator in global authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID.",
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "User deleted"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
},
"get": {
"description": "Get user from authenticator in global authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID.",
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
},
"put": {
"description": "Update user in authenticator in global authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID.",
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"regular_user": {
"summary": "Update regular user",
"value": {
"password": "newsecret"
}
},
"super_user": {
"summary": "Update user and promote to superuser",
"value": {
"is_superuser": true,
"password": "newsecret"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.request_user_update"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
}
},
"/authentication/{id}/import_users": {
"post": {
"description": "Import users into authenticator in global authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"properties": {
"filename": {
"format": "binary",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"204": {
"description": "Users imported"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
}
},
"/mqtt/delayed": {
"get": {
"description": "Get delayed status",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/modules.delayed"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
},
"put": {
"description": "Enable or disable delayed, set max delayed messages",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/modules.delayed"
}
}
}
},
"responses": {
"200": {
"description": "Enable or disable delayed successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/modules.delayed"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Max limit illegality",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
}
},
"/configs/limiter": {
"get": {
"description": "Get the sub-configurations under *limiter*",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/limiter.limiter"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *limiter*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/limiter.limiter"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/limiter.limiter"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/gateways/lwm2m/clients/{clientid}/observe": {
"post": {
"description": "Observe or Cancel observe a resource",
"parameters": [
{
"example": "urn:oma:lwm2m:oma:2",
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
},
{
"example": "/3/0/7",
"in": "query",
"name": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"example": true,
"in": "query",
"name": "enable",
"required": true,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENT_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Clientid not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Observe a Resource",
"tags": [
"LwM2M Gateways"
]
}
},
"/plugins/{name}": {
"delete": {
"description": "Uninstall a plugin package.",
"parameters": [
{
"$ref": "#/components/parameters/plugins.name"
}
],
"responses": {
"204": {
"description": "Uninstall successfully"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Plugin Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Plugins"
]
},
"get": {
"description": "Describe a plugin according `release.json` and `README.md`.",
"parameters": [
{
"$ref": "#/components/parameters/plugins.name"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/plugins.plugin"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Plugin Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Plugins"
]
}
},
"/bridges/{id}/metrics/reset": {
"put": {
"description": "Reset a bridge metrics by Id",
"parameters": [
{
"description": "The bridge Id. Must be of format {type}:{name}",
"example": "webhook:webhook_example",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Reset success"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "RPC Call Failed",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Reset Bridge Metrics",
"tags": [
"Bridges"
]
}
},
"/status": {
"get": {
"description": "Serves as a health check for the node. Returns a plain text response describing the status of the node. This endpoint requires no authentication.
Returns status code 200 if the EMQX application is up and running, 503 otherwise.
This API was introduced in v5.0.10.
The GET `/status` endpoint (without the `/api/...` prefix) is also an alias to this endpoint and works in the same way. This alias has been available since v5.0.0.",
"parameters": [],
"responses": {
"200": {
"description": "Node emqx@127.0.0.1 is started
emqx is running"
},
"503": {
"description": "Node emqx@127.0.0.1 is stopped
emqx is not_running"
}
},
"security": [],
"tags": [
"Status"
]
}
},
"/topics/{topic}": {
"get": {
"description": "Lookup topic info by name",
"parameters": [
{
"description": "Topic Name",
"example": "",
"in": "path",
"name": "topic",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_topics.topic"
},
"type": "array"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"TOPIC_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Topic not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Topics"
]
}
},
"/stats": {
"get": {
"description": "EMQX stats",
"parameters": [
{
"$ref": "#/components/parameters/emqx_mgmt_api_stats.aggregate"
}
],
"responses": {
"200": {
"description": "List stats ok",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_stats.aggergate_data"
},
"type": "array"
},
{
"$ref": "#/components/schemas/emqx_mgmt_api_stats.node_stats_data"
}
]
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Metrics"
]
}
},
"/monitor_current": {
"get": {
"description": "Current status. Gauge and rate.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_dashboard_monitor_api.sampler_current"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Metrics"
]
}
},
"/listeners/{listener_id}/authentication/{id}": {
"delete": {
"description": "Delete authenticator from listener authentication chain.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Authenticator deleted"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
},
"get": {
"description": "Get authenticator from listener authentication chain.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
},
"put": {
"description": "Update authenticator from listener authentication chain.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"responses": {
"204": {
"description": "Authenticator updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"ALREADY_EXISTS"
],
"type": "string"
},
"message": {
"description": "ALREADY_EXISTS",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
}
},
"/authorization/sources/built_in_database/rules/users": {
"get": {
"description": "Show the list of rules for users",
"parameters": [
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
},
{
"description": "Fuzzy search `username` as substring",
"in": "query",
"name": "like_username",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"password_based:built_in_database": {
"summary": "Username",
"value": {
"data": [
{
"rules": [
{
"action": "publish",
"permission": "allow",
"topic": "test/toopic/1"
},
{
"action": "subscribe",
"permission": "allow",
"topic": "test/toopic/2"
},
{
"action": "all",
"permission": "deny",
"topic": "eq test/#"
}
],
"username": "user1"
}
],
"meta": {
"count": 1,
"limit": 100,
"page": 1
}
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.username_response_data"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"post": {
"description": "Add new rule for 'username'",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"examples": {
"password_based:built_in_database": {
"summary": "Username",
"value": [
{
"rules": [
{
"action": "publish",
"permission": "allow",
"topic": "test/toopic/1"
},
{
"action": "subscribe",
"permission": "allow",
"topic": "test/toopic/2"
},
{
"action": "all",
"permission": "deny",
"topic": "eq test/#"
}
],
"username": "user1"
}
]
}
},
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rules_for_username"
},
"type": "array"
}
}
}
},
"responses": {
"204": {
"description": "Created"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad username or bad rule schema",
"type": "string"
}
},
"type": "object"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"ALREADY_EXISTS"
],
"type": "string"
},
"message": {
"description": "ALREADY_EXISTS",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/nodes/{node}/stats": {
"get": {
"description": "Get node stats",
"parameters": [
{
"$ref": "#/components/parameters/emqx_mgmt_api_nodes.node_name"
}
],
"responses": {
"200": {
"description": "Get node stats successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_stats.node_stats_data"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"SOURCE_ERROR"
],
"type": "string"
},
"message": {
"description": "Node error",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Nodes"
]
}
},
"/exhooks/{name}": {
"delete": {
"description": "Delete the server",
"parameters": [
{
"description": "The Exhook server name",
"example": "default",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": ""
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Server not found",
"type": "string"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_RPC"
],
"type": "string"
},
"message": {
"description": "Bad RPC",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"ExHook"
]
},
"get": {
"description": "Get the detail information of Exhook server",
"parameters": [
{
"description": "The Exhook server name",
"example": "default",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/exhook.detail_server_info"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Server not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"ExHook"
]
},
"put": {
"description": "Update the server",
"parameters": [
{
"description": "The Exhook server name",
"example": "default",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"auto_reconnect": "60s",
"enable": true,
"failed_action": "deny",
"name": "default",
"pool_size": 8,
"request_timeout": "5s",
"ssl": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"enable": false,
"keyfile": "/etc/emqx/certs/key.pem"
},
"url": "http://127.0.0.1:8081"
},
"schema": {
"$ref": "#/components/schemas/exhook.server_config"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/exhook.detail_server_info"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Server not found",
"type": "string"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_RPC"
],
"type": "string"
},
"message": {
"description": "Bad RPC",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"ExHook"
]
}
},
"/prometheus": {
"get": {
"description": "Get Prometheus config info",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"enable": true,
"headers": {
"header-name": "header-value"
},
"interval": "15s",
"job_name": "${name}/instance/${name}~${host}",
"mnesia_collector": "enabled",
"push_gateway_server": "http://127.0.0.1:9091",
"vm_dist_collector": "enabled",
"vm_memory_collector": "enabled",
"vm_msacc_collector": "enabled",
"vm_statistics_collector": "enabled",
"vm_system_info_collector": "enabled"
},
"schema": {
"$ref": "#/components/schemas/prometheus.prometheus"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Monitor"
]
},
"put": {
"description": "Update Prometheus config",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"example": {
"enable": true,
"headers": {
"header-name": "header-value"
},
"interval": "15s",
"job_name": "${name}/instance/${name}~${host}",
"mnesia_collector": "enabled",
"push_gateway_server": "http://127.0.0.1:9091",
"vm_dist_collector": "enabled",
"vm_memory_collector": "enabled",
"vm_msacc_collector": "enabled",
"vm_statistics_collector": "enabled",
"vm_system_info_collector": "enabled"
},
"schema": {
"$ref": "#/components/schemas/prometheus.prometheus"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"enable": true,
"headers": {
"header-name": "header-value"
},
"interval": "15s",
"job_name": "${name}/instance/${name}~${host}",
"mnesia_collector": "enabled",
"push_gateway_server": "http://127.0.0.1:9091",
"vm_dist_collector": "enabled",
"vm_memory_collector": "enabled",
"vm_msacc_collector": "enabled",
"vm_statistics_collector": "enabled",
"vm_system_info_collector": "enabled"
},
"schema": {
"$ref": "#/components/schemas/prometheus.prometheus"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Monitor"
]
}
},
"/mqtt/auto_subscribe": {
"get": {
"description": "Get auto subscribe topic list",
"parameters": [],
"responses": {
"200": {
"description": "After the device logs in successfully, the subscription is automatically completed for the device through the pre-defined subscription representation. Supports the use of placeholders.",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/auto_subscribe.topic"
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Auto Subscribe"
]
},
"put": {
"description": "Update auto subscribe topic list",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/auto_subscribe.topic"
},
"type": "array"
}
}
}
},
"responses": {
"200": {
"description": "After the device logs in successfully, the subscription is automatically completed for the device through the pre-defined subscription representation. Supports the use of placeholders.",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/auto_subscribe.topic"
},
"type": "array"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"EXCEED_LIMIT"
],
"type": "string"
},
"message": {
"description": "Auto Subscribe topics max limit",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Auto Subscribe"
]
}
},
"/gateways/{name}/listeners/{id}/authentication": {
"delete": {
"description": "Remove authenticator for the listener.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Deleted"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Delete the Listener's Authenticator",
"tags": [
"Gateway Listeners"
]
},
"get": {
"description": "Get the listener's authenticator configs.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"204": {
"description": "Authentication or listener does not existed"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Get the Listener's Authenticator",
"tags": [
"Gateway Listeners"
]
},
"post": {
"description": "Enable authenticator for specified listener for client authentication.
When authenticator is enabled for a listener, all clients connecting to that listener will use that authenticator for authentication.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Create an Authenticator for a Listener",
"tags": [
"Gateway Listeners"
]
},
"put": {
"description": "Update authenticator configs for the listener, or disable/enable it.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Update the Listener Authenticator configs",
"tags": [
"Gateway Listeners"
]
}
},
"/gateways/{name}/listeners": {
"get": {
"description": "Gets a list of gateway listeners. This interface returns all the configs of the listener (including the authenticator on that listener), as well as the status of that listener running in the cluster.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": [
{
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22213",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-def",
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
}
}
],
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
},
"type": "dtls",
"udp_options": {
"active_n": 100,
"backlog": 1024
}
},
{
"acceptors": 16,
"bind": "22214",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"ciphers": "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"user_lookup_fun": "emqx_tls_psk:lookup",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-psk",
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
}
}
],
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
},
"type": "dtls"
},
{
"acceptors": 16,
"authentication": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256"
},
"user_id_type": "username"
},
"bind": "22215",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-with-authn",
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
}
}
],
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
},
"type": "tcp"
},
{
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22211",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "ssl-def",
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
}
}
],
"ssl_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
]
},
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
},
"tcp_options": {
"active_n": 100,
"backlog": 1024
},
"type": "ssl"
},
{
"acceptors": 16,
"bind": "22210",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-def",
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
}
}
],
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
},
"tcp_options": {
"active_n": 100,
"backlog": 1024,
"buffer": "10KB",
"high_watermark": "1MB",
"nodelay": false,
"recbuf": "10KB",
"reuseaddr": true,
"send_timeout": "15s",
"send_timeout_close": true,
"sndbuf": "10KB"
},
"type": "tcp"
},
{
"bind": "22212",
"name": "udp-def",
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
}
}
],
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
},
"type": "udp",
"udp_options": {
"active_n": 100,
"buffer": "10KB",
"recbuf": "10KB",
"reuseaddr": true,
"sndbuf": "10KB"
}
}
],
"schema": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api_listeners.dtls_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api_listeners.udp_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api_listeners.ssl_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api_listeners.tcp_listener"
}
]
},
"type": "array"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "List All Listeners",
"tags": [
"Gateway Listeners"
]
},
"post": {
"description": "Create the gateway listener.
Note: For listener types not supported by a gateway, this API returns `400: BAD_REQUEST`.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"dtls_listener": {
"summary": "A simple dtls listener example",
"value": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22213",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-def",
"type": "dtls",
"udp_options": {
"active_n": 100,
"backlog": 1024
}
}
},
"dtls_listener_with_psk_ciphers": {
"summary": "A dtls listener with PSK example",
"value": {
"acceptors": 16,
"bind": "22214",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"ciphers": "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"user_lookup_fun": "emqx_tls_psk:lookup",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-psk",
"type": "dtls"
}
},
"lisetner_with_authn": {
"summary": "A tcp listener with authentication example",
"value": {
"acceptors": 16,
"authentication": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256"
},
"user_id_type": "username"
},
"bind": "22215",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-with-authn",
"type": "tcp"
}
},
"ssl_listener": {
"summary": "A simple ssl listener example",
"value": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22211",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "ssl-def",
"ssl_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
]
},
"tcp_options": {
"active_n": 100,
"backlog": 1024
},
"type": "ssl"
}
},
"tcp_listener": {
"summary": "A simple tcp listener example",
"value": {
"acceptors": 16,
"bind": "22210",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-def",
"tcp_options": {
"active_n": 100,
"backlog": 1024,
"buffer": "10KB",
"high_watermark": "1MB",
"nodelay": false,
"recbuf": "10KB",
"reuseaddr": true,
"send_timeout": "15s",
"send_timeout_close": true,
"sndbuf": "10KB"
},
"type": "tcp"
}
},
"udp_listener": {
"summary": "A simple udp listener example",
"value": {
"bind": "22212",
"name": "udp-def",
"type": "udp",
"udp_options": {
"active_n": 100,
"buffer": "10KB",
"recbuf": "10KB",
"reuseaddr": true,
"sndbuf": "10KB"
}
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.dtls_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.udp_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.ssl_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.tcp_listener"
}
]
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"examples": {
"dtls_listener": {
"summary": "A simple dtls listener example",
"value": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22213",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-def",
"type": "dtls",
"udp_options": {
"active_n": 100,
"backlog": 1024
}
}
},
"dtls_listener_with_psk_ciphers": {
"summary": "A dtls listener with PSK example",
"value": {
"acceptors": 16,
"bind": "22214",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"ciphers": "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"user_lookup_fun": "emqx_tls_psk:lookup",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-psk",
"type": "dtls"
}
},
"lisetner_with_authn": {
"summary": "A tcp listener with authentication example",
"value": {
"acceptors": 16,
"authentication": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256"
},
"user_id_type": "username"
},
"bind": "22215",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-with-authn",
"type": "tcp"
}
},
"ssl_listener": {
"summary": "A simple ssl listener example",
"value": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22211",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "ssl-def",
"ssl_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
]
},
"tcp_options": {
"active_n": 100,
"backlog": 1024
},
"type": "ssl"
}
},
"tcp_listener": {
"summary": "A simple tcp listener example",
"value": {
"acceptors": 16,
"bind": "22210",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-def",
"tcp_options": {
"active_n": 100,
"backlog": 1024,
"buffer": "10KB",
"high_watermark": "1MB",
"nodelay": false,
"recbuf": "10KB",
"reuseaddr": true,
"send_timeout": "15s",
"send_timeout_close": true,
"sndbuf": "10KB"
},
"type": "tcp"
}
},
"udp_listener": {
"summary": "A simple udp listener example",
"value": {
"bind": "22212",
"name": "udp-def",
"type": "udp",
"udp_options": {
"active_n": 100,
"buffer": "10KB",
"recbuf": "10KB",
"reuseaddr": true,
"sndbuf": "10KB"
}
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.dtls_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.udp_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.ssl_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.tcp_listener"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Add a Listener",
"tags": [
"Gateway Listeners"
]
}
},
"/configs/sys_topics": {
"get": {
"description": "Get the sub-configurations under *sys_topics*",
"parameters": [],
"responses": {
"200": {
"description": "System topics configuration.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.sys_topics"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *sys_topics*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.sys_topics"
}
}
}
},
"responses": {
"200": {
"description": "System topics configuration.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.sys_topics"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/authorization/sources/built_in_database/rules/clients": {
"get": {
"description": "Show the list of rules for clients",
"parameters": [
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
},
{
"description": "Fuzzy search `clientid` as substring",
"in": "query",
"name": "like_clientid",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"password_based:built_in_database": {
"summary": "ClientID",
"value": {
"data": [
{
"clientid": "client1",
"rules": [
{
"action": "publish",
"permission": "allow",
"topic": "test/toopic/1"
},
{
"action": "subscribe",
"permission": "allow",
"topic": "test/toopic/2"
},
{
"action": "all",
"permission": "deny",
"topic": "eq test/#"
}
]
}
],
"meta": {
"count": 1,
"limit": 100,
"page": 1
}
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.clientid_response_data"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"post": {
"description": "Add new rule for 'clientid'",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"examples": {
"password_based:built_in_database": {
"summary": "ClientID",
"value": [
{
"clientid": "client1",
"rules": [
{
"action": "publish",
"permission": "allow",
"topic": "test/toopic/1"
},
{
"action": "subscribe",
"permission": "allow",
"topic": "test/toopic/2"
},
{
"action": "all",
"permission": "deny",
"topic": "eq test/#"
}
]
}
]
}
},
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rules_for_clientid"
},
"type": "array"
}
}
}
},
"responses": {
"204": {
"description": "Created"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad clientid or bad rule schema",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/mqtt/delayed/messages/{node}/{msgid}": {
"delete": {
"description": "Delete delayed message",
"parameters": [
{
"description": "The node where message from",
"in": "path",
"name": "node",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Delayed Message ID",
"in": "path",
"name": "msgid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Delete delayed message success"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"MESSAGE_ID_SCHEMA_ERROR",
"INVALID_NODE"
],
"type": "string"
},
"message": {
"description": "Bad Message ID format",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"MESSAGE_ID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Message ID not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
},
"get": {
"description": "View delayed message",
"parameters": [
{
"description": "The node where message from",
"in": "path",
"name": "node",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Delayed Message ID",
"in": "path",
"name": "msgid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_delayed_api.message_without_payload"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"MESSAGE_ID_SCHEMA_ERROR",
"INVALID_NODE"
],
"type": "string"
},
"message": {
"description": "Bad Message ID format",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"MESSAGE_ID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Message ID not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
}
},
"/monitor_current/nodes/{node}": {
"get": {
"description": "Node current status. Gauge and rate.",
"parameters": [
{
"description": "EMQX node name.",
"example": "emqx@127.0.0.1",
"in": "path",
"name": "node",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_dashboard_monitor_api.sampler_current"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_RPC"
],
"type": "string"
},
"message": {
"description": "Bad RPC",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Metrics"
]
}
},
"/telemetry/status": {
"get": {
"description": "Get telemetry status",
"parameters": [],
"responses": {
"200": {
"description": "Get telemetry status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_telemetry_api.status"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Telemetry"
]
},
"put": {
"description": "Enable or disable telemetry",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_telemetry_api.status"
}
}
}
},
"responses": {
"200": {
"description": "Enable or disable telemetry",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_telemetry_api.status"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Telemetry"
]
}
},
"/authentication/{id}/users": {
"get": {
"description": "List users in authenticator in global authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
},
{
"description": "Fuzzy search user_id (username or clientid).",
"in": "query",
"name": "like_user_id",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Is superuser",
"in": "query",
"name": "is_superuser",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"data": [
{
"user_id": "user1"
},
{
"is_superuser": true,
"user_id": "user2"
}
],
"meta": {
"count": 300,
"limit": 20,
"page": 0
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_users"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
},
"post": {
"description": "Create users for authenticator in global authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"regular_user": {
"summary": "Regular user",
"value": {
"password": "secret",
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"password": "secret",
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.request_user_create"
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"examples": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
}
},
"/cluster": {
"get": {
"description": "Get cluster info",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"description": "Cluster name",
"type": "string"
},
"nodes": {
"description": "Node name",
"items": {
"type": "string"
},
"type": "array"
},
"self": {
"description": "Self node name",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Cluster"
]
}
},
"/plugins/{name}/{action}": {
"put": {
"description": "start/stop a installed plugin.
- **start**: start the plugin.
- **stop**: stop the plugin.
",
"parameters": [
{
"$ref": "#/components/parameters/plugins.name"
},
{
"description": "Action",
"in": "path",
"name": "action",
"required": true,
"schema": {
"enum": [
"start",
"stop"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Plugin Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Plugins"
]
}
},
"/gateways/{name}/clients/{clientid}": {
"delete": {
"description": "Kick out the gateway client",
"parameters": [
{
"description": "Client ID",
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Gateway Name",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Kicked"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Kick out Client",
"tags": [
"Gateway Clients"
]
},
"get": {
"description": "Get the gateway client information",
"parameters": [
{
"description": "Client ID",
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Gateway Name",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"general_client": {
"summary": "General Client Info",
"value": {
"send_pkt": 1,
"mailbox_len": 0,
"recv_cnt": 1,
"clean_start": true,
"connected": true,
"clientid": "MzAyMzEzNTUwNzk1NDA1MzYyMzIwNzUxNjQwMTY1NzQ0NjE",
"connected_at": "2021-12-07T10:44:02.721+08:00",
"subscriptions_max": "infinity",
"inflight_max": "infinity",
"awaiting_rel_max": "infinity",
"username": "guest",
"is_bridge": false,
"reductions": 72022,
"expiry_interval": 0,
"proto_name": "STOMP",
"subscriptions_cnt": 0,
"send_msg": 0,
"proto_ver": "1.0",
"mqueue_len": 0,
"inflight_cnt": 0,
"awaiting_rel_cnt": 0,
"disconnected_at": null,
"recv_oct": 56,
"send_oct": 61,
"mqueue_max": "infinity",
"keepalive": 0,
"ip_address": "127.0.0.1",
"recv_pkt": 1,
"node": "emqx@127.0.0.1",
"created_at": "2021-12-07T10:44:02.721+08:00",
"mqueue_dropped": 0,
"heap_size": 4185,
"recv_msg": 0,
"port": 50675,
"send_cnt": 1
}
},
"lwm2m_client": {
"summary": "LwM2M Client Info",
"value": {
"send_pkt": 1,
"mailbox_len": 0,
"recv_cnt": 1,
"clean_start": true,
"connected": true,
"clientid": "MzAyMzEzNTUwNzk1NDA1MzYyMzIwNzUxNjQwMTY1NzQ0NjE",
"connected_at": "2021-12-07T10:44:02.721+08:00",
"subscriptions_max": "infinity",
"inflight_max": "infinity",
"awaiting_rel_max": "infinity",
"username": "guest",
"is_bridge": false,
"reductions": 72022,
"expiry_interval": 0,
"proto_name": "LwM2M",
"subscriptions_cnt": 0,
"send_msg": 0,
"proto_ver": "1.0",
"mqueue_len": 0,
"inflight_cnt": 0,
"awaiting_rel_cnt": 0,
"disconnected_at": null,
"recv_oct": 56,
"send_oct": 61,
"mqueue_max": "infinity",
"keepalive": 0,
"ip_address": "127.0.0.1",
"recv_pkt": 1,
"node": "emqx@127.0.0.1",
"created_at": "2021-12-07T10:44:02.721+08:00",
"endpoint_name": "urn:imei:154928475237123",
"mqueue_dropped": 0,
"heap_size": 4185,
"recv_msg": 0,
"port": 50675,
"send_cnt": 1,
"lifetime": 86400
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api_clients.exproto_client"
},
{
"$ref": "#/components/schemas/emqx_gateway_api_clients.lwm2m_client"
},
{
"$ref": "#/components/schemas/emqx_gateway_api_clients.coap_client"
},
{
"$ref": "#/components/schemas/emqx_gateway_api_clients.mqttsn_client"
},
{
"$ref": "#/components/schemas/emqx_gateway_api_clients.stomp_client"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Get Client Info",
"tags": [
"Gateway Clients"
]
}
},
"/publish/bulk": {
"post": {
"description": "
Publish a batch of messages.
Possible HTTP response status code are:
200: All messages are delivered to at least one subscriber;
202: At least one message was not delivered to any subscriber;
400: At least one message is invalid. For example bad topic name, or QoS is out of range;
503: Failed to deliver at least one of the messages;
In case there is at lest one invalid message in the batch, the HTTP response body
is the same as for /publish API.
Otherwise the HTTP response body is an array of JSON objects indicating the publish
result of each individual message in the batch.
",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_publish.publish_message"
},
"type": "array"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_publish.publish_ok"
},
"type": "array"
}
}
}
},
"202": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_publish.publish_error"
},
"type": "array"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_publish.publish_error"
},
"type": "array"
},
{
"$ref": "#/components/schemas/emqx_mgmt_api_publish.bad_request"
}
]
}
}
}
},
"503": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_publish.publish_error"
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Publish"
]
}
},
"/nodes/{node}/bridges/{id}/{operation}": {
"post": {
"description": "Stop/Restart bridges on a specific node.",
"parameters": [
{
"description": "The node name, e.g. emqx@127.0.0.1",
"example": "emqx@127.0.0.1",
"in": "path",
"name": "node",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "The bridge Id. Must be of format {type}:{name}",
"example": "webhook:webhook_example",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Operations can be one of: stop, restart",
"example": "stop",
"in": "path",
"name": "operation",
"required": true,
"schema": {
"enum": [
"stop",
"restart"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Operation success"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"INVALID_ID"
],
"type": "string"
},
"message": {
"description": "Bad bridge ID",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"FORBIDDEN_REQUEST"
],
"type": "string"
},
"message": {
"description": "forbidden operation",
"type": "string"
}
},
"type": "object"
}
}
}
},
"503": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"SERVICE_UNAVAILABLE"
],
"type": "string"
},
"message": {
"description": "Service unavailable",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Stop/Restart Bridge",
"tags": [
"Bridges"
]
}
},
"/rule_test": {
"post": {
"description": "Test a rule",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_rule_api_schema.rule_test"
}
}
}
},
"responses": {
"200": {
"description": "Rule Test Pass"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Invalid Parameters",
"type": "string"
}
},
"type": "object"
}
}
}
},
"412": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_MATCH"
],
"type": "string"
},
"message": {
"description": "SQL Not Match",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Test a Rule",
"tags": [
"Rules"
]
}
},
"/authorization/sources/built_in_database/rules/clients/{clientid}": {
"delete": {
"description": "Delete rule for 'clientid'",
"parameters": [
{
"$ref": "#/components/parameters/emqx_authz_api_mnesia.clientid"
}
],
"responses": {
"204": {
"description": "Deleted"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad clientid",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "ClientID Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"get": {
"description": "Get rule for 'clientid'",
"parameters": [
{
"$ref": "#/components/parameters/emqx_authz_api_mnesia.clientid"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"password_based:built_in_database": {
"summary": "ClientID",
"value": {
"clientid": "client1",
"rules": [
{
"action": "publish",
"permission": "allow",
"topic": "test/toopic/1"
},
{
"action": "subscribe",
"permission": "allow",
"topic": "test/toopic/2"
},
{
"action": "all",
"permission": "deny",
"topic": "eq test/#"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rules_for_clientid"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"put": {
"description": "Set rule for 'clientid'",
"parameters": [
{
"$ref": "#/components/parameters/emqx_authz_api_mnesia.clientid"
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"password_based:built_in_database": {
"summary": "ClientID",
"value": {
"clientid": "client1",
"rules": [
{
"action": "publish",
"permission": "allow",
"topic": "test/toopic/1"
},
{
"action": "subscribe",
"permission": "allow",
"topic": "test/toopic/2"
},
{
"action": "all",
"permission": "deny",
"topic": "eq test/#"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rules_for_clientid"
}
}
}
},
"responses": {
"204": {
"description": "Updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad clientid or bad rule schema",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/configs/sysmon": {
"get": {
"description": "Get the sub-configurations under *sysmon*",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.sysmon"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *sysmon*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.sysmon"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.sysmon"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/clients/{clientid}/authorization/cache": {
"delete": {
"description": "Clean client authz cache in the cluster.",
"parameters": [
{
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Kick out client successfully"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENTID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Clients"
]
},
"get": {
"description": "Get client authz cache in the cluster.",
"parameters": [
{
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_clients.authz_cache"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENTID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Clients"
]
}
},
"/cluster/{node}/force_leave": {
"delete": {
"description": "Force leave node from cluster",
"parameters": [
{
"$ref": "#/components/parameters/cluster.node"
}
],
"responses": {
"204": {
"description": "Delete successfully"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Cluster"
]
}
},
"/gateways/{name}/listeners/{id}": {
"delete": {
"description": "Delete the gateway listener. All connected clients under the deleted listener will be disconnected.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Delete the Listener",
"tags": [
"Gateway Listeners"
]
},
"get": {
"description": "Get the gateway listener configs",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"dtls_listener": {
"summary": "A simple dtls listener example",
"value": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22213",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-def",
"type": "dtls",
"udp_options": {
"active_n": 100,
"backlog": 1024
}
}
},
"dtls_listener_with_psk_ciphers": {
"summary": "A dtls listener with PSK example",
"value": {
"acceptors": 16,
"bind": "22214",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"ciphers": "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"user_lookup_fun": "emqx_tls_psk:lookup",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-psk",
"type": "dtls"
}
},
"lisetner_with_authn": {
"summary": "A tcp listener with authentication example",
"value": {
"acceptors": 16,
"authentication": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256"
},
"user_id_type": "username"
},
"bind": "22215",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-with-authn",
"type": "tcp"
}
},
"ssl_listener": {
"summary": "A simple ssl listener example",
"value": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22211",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "ssl-def",
"ssl_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
]
},
"tcp_options": {
"active_n": 100,
"backlog": 1024
},
"type": "ssl"
}
},
"tcp_listener": {
"summary": "A simple tcp listener example",
"value": {
"acceptors": 16,
"bind": "22210",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-def",
"tcp_options": {
"active_n": 100,
"backlog": 1024,
"buffer": "10KB",
"high_watermark": "1MB",
"nodelay": false,
"recbuf": "10KB",
"reuseaddr": true,
"send_timeout": "15s",
"send_timeout_close": true,
"sndbuf": "10KB"
},
"type": "tcp"
}
},
"udp_listener": {
"summary": "A simple udp listener example",
"value": {
"bind": "22212",
"name": "udp-def",
"type": "udp",
"udp_options": {
"active_n": 100,
"buffer": "10KB",
"recbuf": "10KB",
"reuseaddr": true,
"sndbuf": "10KB"
}
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.dtls_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.udp_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.ssl_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.tcp_listener"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Get the Listener Configs",
"tags": [
"Gateway Listeners"
]
},
"put": {
"description": "Update the gateway listener. The listener being updated performs a restart and all clients connected to that listener will be disconnected.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"dtls_listener": {
"summary": "A simple dtls listener example",
"value": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22213",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-def",
"type": "dtls",
"udp_options": {
"active_n": 100,
"backlog": 1024
}
}
},
"dtls_listener_with_psk_ciphers": {
"summary": "A dtls listener with PSK example",
"value": {
"acceptors": 16,
"bind": "22214",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"ciphers": "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"user_lookup_fun": "emqx_tls_psk:lookup",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-psk",
"type": "dtls"
}
},
"lisetner_with_authn": {
"summary": "A tcp listener with authentication example",
"value": {
"acceptors": 16,
"authentication": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256"
},
"user_id_type": "username"
},
"bind": "22215",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-with-authn",
"type": "tcp"
}
},
"ssl_listener": {
"summary": "A simple ssl listener example",
"value": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22211",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "ssl-def",
"ssl_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
]
},
"tcp_options": {
"active_n": 100,
"backlog": 1024
},
"type": "ssl"
}
},
"tcp_listener": {
"summary": "A simple tcp listener example",
"value": {
"acceptors": 16,
"bind": "22210",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-def",
"tcp_options": {
"active_n": 100,
"backlog": 1024,
"buffer": "10KB",
"high_watermark": "1MB",
"nodelay": false,
"recbuf": "10KB",
"reuseaddr": true,
"send_timeout": "15s",
"send_timeout_close": true,
"sndbuf": "10KB"
},
"type": "tcp"
}
},
"udp_listener": {
"summary": "A simple udp listener example",
"value": {
"bind": "22212",
"name": "udp-def",
"type": "udp",
"udp_options": {
"active_n": 100,
"buffer": "10KB",
"recbuf": "10KB",
"reuseaddr": true,
"sndbuf": "10KB"
}
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.dtls_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.udp_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.ssl_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.tcp_listener"
}
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"dtls_listener": {
"summary": "A simple dtls listener example",
"value": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22213",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-def",
"type": "dtls",
"udp_options": {
"active_n": 100,
"backlog": 1024
}
}
},
"dtls_listener_with_psk_ciphers": {
"summary": "A dtls listener with PSK example",
"value": {
"acceptors": 16,
"bind": "22214",
"dtls_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"ciphers": "RSA-PSK-AES256-GCM-SHA384,RSA-PSK-AES256-CBC-SHA384,RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"user_lookup_fun": "emqx_tls_psk:lookup",
"verify": "verify_none",
"versions": [
"dtlsv1.2",
"dtlsv1"
]
},
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "dtls-psk",
"type": "dtls"
}
},
"lisetner_with_authn": {
"summary": "A tcp listener with authentication example",
"value": {
"acceptors": 16,
"authentication": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256"
},
"user_id_type": "username"
},
"bind": "22215",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-with-authn",
"type": "tcp"
}
},
"ssl_listener": {
"summary": "A simple ssl listener example",
"value": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "22211",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "ssl-def",
"ssl_options": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"fail_if_no_peer_cert": false,
"keyfile": "/etc/emqx/certs/key.pem",
"verify": "verify_none",
"versions": [
"tlsv1.3",
"tlsv1.2",
"tlsv1.1",
"tlsv1"
]
},
"tcp_options": {
"active_n": 100,
"backlog": 1024
},
"type": "ssl"
}
},
"tcp_listener": {
"summary": "A simple tcp listener example",
"value": {
"acceptors": 16,
"bind": "22210",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "tcp-def",
"tcp_options": {
"active_n": 100,
"backlog": 1024,
"buffer": "10KB",
"high_watermark": "1MB",
"nodelay": false,
"recbuf": "10KB",
"reuseaddr": true,
"send_timeout": "15s",
"send_timeout_close": true,
"sndbuf": "10KB"
},
"type": "tcp"
}
},
"udp_listener": {
"summary": "A simple udp listener example",
"value": {
"bind": "22212",
"name": "udp-def",
"type": "udp",
"udp_options": {
"active_n": 100,
"buffer": "10KB",
"recbuf": "10KB",
"reuseaddr": true,
"sndbuf": "10KB"
}
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.dtls_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.udp_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.ssl_listener"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.tcp_listener"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Update the Listener Configs",
"tags": [
"Gateway Listeners"
]
}
},
"/gateways/{name}/enable/{enable}": {
"put": {
"description": "Update the gateway basic configurations and running status.
Note: The Authentication and Listener configurations should be updated by other special APIs. ",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Whether or not gateway is enabled",
"example": true,
"in": "path",
"name": "enable",
"required": true,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"204": {
"description": "Gateway configuration updated"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Enable or disable gateway",
"tags": [
"Gateways"
]
}
},
"/rules": {
"get": {
"description": "List all rules",
"parameters": [
{
"description": "Filter enable/disable rules",
"in": "query",
"name": "enable",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"description": "Filter rules by from(topic), exact match",
"in": "query",
"name": "from",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter rules by id, Substring matching",
"in": "query",
"name": "like_id",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter rules by from(topic), Substring matching",
"in": "query",
"name": "like_from",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter rules by description, Substring matching",
"in": "query",
"name": "like_description",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter rules by from(topic), Mqtt topic matching",
"in": "query",
"name": "match_from",
"required": false,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"description": "List of rules",
"items": {
"$ref": "#/components/schemas/emqx_rule_api_schema.rule_info"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/public.meta"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Invalid Parameters",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "List Rules",
"tags": [
"Rules"
]
},
"post": {
"description": "Create a new rule using given Id",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_rule_api_schema.rule_creation"
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_rule_api_schema.rule_info"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Invalid Parameters",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Create a Rule",
"tags": [
"Rules"
]
}
},
"/authentication/{id}/status": {
"get": {
"description": "Get authenticator status from global authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"status_metrics": {
"summary": "Authn status metrics",
"value": {
"metrics": {
"failed": 0,
"nomatch": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"success": 0,
"total": 0
},
"node_error": [],
"node_metrics": [
{
"metrics": {
"failed": 0,
"matched": 0,
"nomatch": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"total": 0
},
"node": "emqx@127.0.0.1"
}
],
"node_resource_metrics": [
{
"metrics": {
"failed": 0,
"matched": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"success": 0
},
"node": "emqx@127.0.0.1"
}
],
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": "connected"
}
],
"resource_metrics": {
"failed": 0,
"matched": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"success": 0
},
"status": "connected"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_schema.metrics_status_fields"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"INTERNAL_ERROR"
],
"type": "string"
},
"message": {
"description": "Internal Service Error",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
}
},
"/mqtt/topic_rewrite": {
"get": {
"description": "List all rewrite rules",
"parameters": [],
"responses": {
"200": {
"description": "List all rewrite rules",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/modules.rewrite"
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
},
"put": {
"description": "Update all rewrite rules",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/modules.rewrite"
},
"type": "array"
}
}
}
},
"responses": {
"200": {
"description": "Update all rewrite rules",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/modules.rewrite"
},
"type": "array"
}
}
}
},
"413": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"EXCEED_LIMIT"
],
"type": "string"
},
"message": {
"description": "Rules count exceed max limit",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
}
},
"/gateways": {
"get": {
"description": "This API returns an overview info for the specified or all gateways.
including current running status, number of connections, listener status, etc.",
"parameters": [
{
"description": "Filter gateways by status.
It is enum with `running`, `stopped`, `unloaded`",
"example": "running",
"in": "query",
"name": "status",
"required": false,
"schema": {
"enum": [
"running",
"stopped",
"unloaded"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": [
{
"name": "coap",
"status": "unloaded"
},
{
"name": "exproto",
"status": "unloaded"
},
{
"created_at": "2021-12-08T14:41:26.171+08:00",
"current_connections": 0,
"listeners": [
{
"id": "lwm2m:udp:default",
"name": "default",
"running": true,
"type": "udp"
}
],
"max_connections": 1024000,
"name": "lwm2m",
"node_status": [
{
"current_connections": 0,
"max_connections": 1024000,
"node": "node@127.0.0.1",
"status": "running"
}
],
"started_at": "2021-12-08T14:41:26.202+08:00",
"status": "running"
},
{
"created_at": "2021-12-08T14:41:45.071+08:00",
"current_connections": 0,
"listeners": [
{
"id": "mqttsn:udp:default",
"name": "default",
"running": false,
"type": "udp"
}
],
"max_connections": 1024000,
"name": "mqttsn",
"node_status": [
{
"current_connections": 0,
"max_connections": 1024000,
"node": "node@127.0.0.1",
"status": "running"
}
],
"status": "stopped",
"stopped_at": "2021-12-08T14:56:35.576+08:00"
},
{
"created_at": "2021-12-08T14:42:15.272+08:00",
"current_connections": 0,
"listeners": [
{
"id": "stomp:tcp:default",
"name": "default",
"running": true,
"type": "tcp"
}
],
"max_connections": 1024000,
"name": "stomp",
"node_status": [
{
"current_connections": 0,
"max_connections": 1024000,
"node": "node@127.0.0.1",
"status": "running"
}
],
"started_at": "2021-12-08T14:42:15.274+08:00",
"status": "running"
}
],
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_gateway_api.gateway_overview"
},
"type": "array"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "List All Gateways",
"tags": [
"Gateways"
]
}
},
"/mqtt/topic_metrics/{topic}": {
"delete": {
"description": "Delete Topic metrics",
"parameters": [
{
"description": "Topic string. Notice: Topic string in url path must be encoded",
"example": "testtopic/1",
"in": "path",
"name": "topic",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Delete Topic metrics"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"TOPIC_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found. Topic metrics not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
},
"get": {
"description": "Get Topic metrics",
"parameters": [
{
"description": "Topic string. Notice: Topic string in url path must be encoded",
"example": "testtopic/1",
"in": "path",
"name": "topic",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Topic",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_topic_metrics_api.topic_metrics"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"TOPIC_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found. Topic metrics not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
}
},
"/bridges_probe": {
"post": {
"description": "
Test creating a new bridge by given ID
The ID must be of format '{type}:{name}'
",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"examples": {
"mqtt_example": {
"summary": "MQTT Bridge",
"value": {
"clean_start": true,
"egress": {
"local": {
"topic": "emqx/#"
},
"remote": {
"payload": "${payload}",
"qos": "${qos}",
"retain": false,
"topic": "from_emqx/${topic}"
}
},
"enable": true,
"ingress": {
"local": {
"payload": "${payload}",
"qos": "${qos}",
"retain": "${retain}",
"topic": "from_aws/${topic}"
},
"remote": {
"qos": 1,
"topic": "aws/#"
}
},
"keepalive": "300s",
"max_inflight": 100,
"mode": "cluster_shareload",
"name": "mqtt_example",
"password": "bar",
"proto_ver": "v4",
"resource_opts": {
"auto_restart_interval": "60s",
"health_check_interval": "15s",
"max_queue_bytes": 104857600,
"query_mode": "sync"
},
"retry_interval": "15s",
"server": "127.0.0.1:1883",
"ssl": {
"enable": false
},
"type": "mqtt",
"username": "foo"
}
},
"webhook_example": {
"summary": "WebHook",
"value": {
"body": "${payload}",
"connect_timeout": "15s",
"enable": true,
"enable_pipelining": 100,
"local_topic": "emqx_webhook/#",
"max_retries": 3,
"method": "post",
"name": "webhook_example",
"pool_size": 4,
"pool_type": "random",
"request_timeout": "15s",
"resource_opts": {
"async_inflight_window": 100,
"auto_restart_interval": 15000,
"health_check_interval": 15000,
"max_queue_bytes": 104857600,
"query_mode": "async",
"worker_pool_size": 1
},
"ssl": {
"enable": false
},
"type": "webhook",
"url": "http://localhost:9901/messages/${topic}"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/bridge_mqtt.post"
},
{
"$ref": "#/components/schemas/bridge_webhook.post"
}
]
}
}
}
},
"responses": {
"204": {
"description": "Test bridge OK"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"TEST_FAILED"
],
"type": "string"
},
"message": {
"description": "bridge test failed",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Test creating bridge",
"tags": [
"Bridges"
]
}
},
"/monitor/nodes/{node}": {
"get": {
"description": "List the monitor data on the node.",
"parameters": [
{
"description": "EMQX node name.",
"example": "emqx@127.0.0.1",
"in": "path",
"name": "node",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "The latest N seconds data. Like 300 for 5 min.",
"example": 300,
"in": "query",
"name": "latest",
"required": false,
"schema": {
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_dashboard_monitor_api.sampler"
},
"type": "array"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_RPC"
],
"type": "string"
},
"message": {
"description": "Bad RPC",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Metrics"
]
}
},
"/prometheus/stats": {
"get": {
"description": "Get Prometheus Data",
"parameters": [],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
},
"description": "Get Prometheus Data"
}
},
"security": [],
"tags": [
"Monitor"
]
}
},
"/trace/{name}/log_detail": {
"get": {
"description": "get trace log file's metadata, such as size, last update time",
"parameters": [
{
"$ref": "#/components/parameters/trace.name"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/trace.log_file_detail"
},
"type": "array"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Trace Name Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Trace"
]
}
},
"/authentication/{id}": {
"delete": {
"description": "Delete authenticator from global authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Authenticator deleted"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
},
"get": {
"description": "Get authenticator from global authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
},
"put": {
"description": "Update authenticator from global authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"responses": {
"204": {
"description": "Authenticator updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"ALREADY_EXISTS"
],
"type": "string"
},
"message": {
"description": "ALREADY_EXISTS",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
}
},
"/publish": {
"post": {
"description": "
Publish one message.
Possible HTTP status response codes are:
200: The message is delivered to at least one subscriber;
202: No matched subscribers;
400: Message is invalid. for example bad topic name, or QoS is out of range;
503: Failed to deliver the message to subscriber(s);
",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_publish.publish_message"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_publish.publish_ok"
}
}
}
},
"202": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_publish.publish_error"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_publish.publish_error"
},
"type": "array"
},
{
"$ref": "#/components/schemas/emqx_mgmt_api_publish.bad_request"
}
]
}
}
}
},
"503": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_publish.publish_error"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Publish"
]
}
},
"/nodes/{node}/metrics": {
"get": {
"description": "Get node metrics",
"parameters": [
{
"$ref": "#/components/parameters/emqx_mgmt_api_nodes.node_name"
}
],
"responses": {
"200": {
"description": "Get node metrics successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_metrics.node_metrics"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"SOURCE_ERROR"
],
"type": "string"
},
"message": {
"description": "Node error",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Nodes"
]
}
},
"/configs/global_zone": {
"get": {
"description": "Get the global zone configs",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"mqtt": {
"description": "Global MQTT configuration.
The configs here work as default values which can be overridden
in zone configs",
"$ref": "#/components/schemas/zone.mqtt"
},
"stats": {
"description": "Enable/disable statistic data collection.
Statistic data such as message receive/send count/rate etc. It provides insights of system performance and helps to diagnose issues. You can find statistic data from the dashboard, or from the '/stats' API.",
"$ref": "#/components/schemas/zone.stats"
},
"flapping_detect": {
"description": "This config controls the allowed maximum number of `CONNECT` packets received
from the same clientid in a time frame defined by `window_time`.
After the limit is reached, successive `CONNECT` requests are forbidden
(banned) until the end of the time period defined by `ban_time`.",
"$ref": "#/components/schemas/zone.flapping_detect"
},
"force_shutdown": {
"description": "When the process message queue length, or the memory bytes
reaches a certain value, the process is forced to close.
Note: \"message queue\" here refers to the \"message mailbox\"
of the Erlang process, not the `mqueue` of QoS 1 and QoS 2.",
"$ref": "#/components/schemas/zone.force_shutdown"
},
"conn_congestion": {
"description": "Settings for `conn_congestion` alarm.
Sometimes the MQTT connection (usually an MQTT subscriber) may
get \"congested\", because there are too many packets to be sent.
The socket tries to buffer the packets until the buffer is
full. If more packets arrive after that, the packets will be
\"pending\" in the queue, and we consider the connection
congested.
Note: `sndbuf` can be set to larger value if the
alarm is triggered too often.
The name of the alarm is of format `conn_congestion//`,
where the `` is the client ID of the congested MQTT connection,
and `` is the username or `unknown_user`.",
"$ref": "#/components/schemas/zone.conn_congestion"
},
"force_gc": {
"description": "Force garbage collection in MQTT connection process after
they process certain number of messages or bytes of data.",
"$ref": "#/components/schemas/zone.force_gc"
},
"overload_protection": {
"description": "Overload protection mechanism monitors the load of the system and temporarily
disables some features (such as accepting new connections) when the load is high.",
"$ref": "#/components/schemas/zone.overload_protection"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update globbal zone configs",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"mqtt": {
"description": "Global MQTT configuration.
The configs here work as default values which can be overridden
in zone configs",
"$ref": "#/components/schemas/zone.mqtt"
},
"stats": {
"description": "Enable/disable statistic data collection.
Statistic data such as message receive/send count/rate etc. It provides insights of system performance and helps to diagnose issues. You can find statistic data from the dashboard, or from the '/stats' API.",
"$ref": "#/components/schemas/zone.stats"
},
"flapping_detect": {
"description": "This config controls the allowed maximum number of `CONNECT` packets received
from the same clientid in a time frame defined by `window_time`.
After the limit is reached, successive `CONNECT` requests are forbidden
(banned) until the end of the time period defined by `ban_time`.",
"$ref": "#/components/schemas/zone.flapping_detect"
},
"force_shutdown": {
"description": "When the process message queue length, or the memory bytes
reaches a certain value, the process is forced to close.
Note: \"message queue\" here refers to the \"message mailbox\"
of the Erlang process, not the `mqueue` of QoS 1 and QoS 2.",
"$ref": "#/components/schemas/zone.force_shutdown"
},
"conn_congestion": {
"description": "Settings for `conn_congestion` alarm.
Sometimes the MQTT connection (usually an MQTT subscriber) may
get \"congested\", because there are too many packets to be sent.
The socket tries to buffer the packets until the buffer is
full. If more packets arrive after that, the packets will be
\"pending\" in the queue, and we consider the connection
congested.
Note: `sndbuf` can be set to larger value if the
alarm is triggered too often.
The name of the alarm is of format `conn_congestion//`,
where the `` is the client ID of the congested MQTT connection,
and `` is the username or `unknown_user`.",
"$ref": "#/components/schemas/zone.conn_congestion"
},
"force_gc": {
"description": "Force garbage collection in MQTT connection process after
they process certain number of messages or bytes of data.",
"$ref": "#/components/schemas/zone.force_gc"
},
"overload_protection": {
"description": "Overload protection mechanism monitors the load of the system and temporarily
disables some features (such as accepting new connections) when the load is high.",
"$ref": "#/components/schemas/zone.overload_protection"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"mqtt": {
"description": "Global MQTT configuration.
The configs here work as default values which can be overridden
in zone configs",
"$ref": "#/components/schemas/zone.mqtt"
},
"stats": {
"description": "Enable/disable statistic data collection.
Statistic data such as message receive/send count/rate etc. It provides insights of system performance and helps to diagnose issues. You can find statistic data from the dashboard, or from the '/stats' API.",
"$ref": "#/components/schemas/zone.stats"
},
"flapping_detect": {
"description": "This config controls the allowed maximum number of `CONNECT` packets received
from the same clientid in a time frame defined by `window_time`.
After the limit is reached, successive `CONNECT` requests are forbidden
(banned) until the end of the time period defined by `ban_time`.",
"$ref": "#/components/schemas/zone.flapping_detect"
},
"force_shutdown": {
"description": "When the process message queue length, or the memory bytes
reaches a certain value, the process is forced to close.
Note: \"message queue\" here refers to the \"message mailbox\"
of the Erlang process, not the `mqueue` of QoS 1 and QoS 2.",
"$ref": "#/components/schemas/zone.force_shutdown"
},
"conn_congestion": {
"description": "Settings for `conn_congestion` alarm.
Sometimes the MQTT connection (usually an MQTT subscriber) may
get \"congested\", because there are too many packets to be sent.
The socket tries to buffer the packets until the buffer is
full. If more packets arrive after that, the packets will be
\"pending\" in the queue, and we consider the connection
congested.
Note: `sndbuf` can be set to larger value if the
alarm is triggered too often.
The name of the alarm is of format `conn_congestion//`,
where the `` is the client ID of the congested MQTT connection,
and `` is the username or `unknown_user`.",
"$ref": "#/components/schemas/zone.conn_congestion"
},
"force_gc": {
"description": "Force garbage collection in MQTT connection process after
they process certain number of messages or bytes of data.",
"$ref": "#/components/schemas/zone.force_gc"
},
"overload_protection": {
"description": "Overload protection mechanism monitors the load of the system and temporarily
disables some features (such as accepting new connections) when the load is high.",
"$ref": "#/components/schemas/zone.overload_protection"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/bridges/{id}/enable/{enable}": {
"put": {
"description": "Enable or Disable bridges on all nodes in the cluster.",
"parameters": [
{
"description": "The bridge Id. Must be of format {type}:{name}",
"example": "webhook:webhook_example",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Whether or not the bridge is enabled",
"example": true,
"in": "path",
"name": "enable",
"required": true,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"204": {
"description": "Success"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"INVALID_ID"
],
"type": "string"
},
"message": {
"description": "Bad bridge ID",
"type": "string"
}
},
"type": "object"
}
}
}
},
"503": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"SERVICE_UNAVAILABLE"
],
"type": "string"
},
"message": {
"description": "Service unavailable",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Enable or Disable Bridge",
"tags": [
"Bridges"
]
}
},
"/configs/cluster": {
"get": {
"description": "Get the sub-configurations under *cluster*",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_conf_schema.cluster"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *cluster*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_conf_schema.cluster"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_conf_schema.cluster"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/bridges/{id}/metrics": {
"get": {
"description": "Get bridge metrics by Id",
"parameters": [
{
"description": "The bridge Id. Must be of format {type}:{name}",
"example": "webhook:webhook_example",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"metrics": {
"description": "Bridge metrics.",
"$ref": "#/components/schemas/bridge.metrics"
},
"node_metrics": {
"description": "Node metrics.",
"items": {
"$ref": "#/components/schemas/bridge.node_metrics"
},
"type": "array"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Bridge not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Get Bridge Metrics",
"tags": [
"Bridges"
]
}
},
"/users": {
"get": {
"description": "Dashboard list users",
"parameters": [],
"responses": {
"200": {
"description": "Dashboard list users",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/dashboard.user"
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Dashboard"
]
},
"post": {
"description": "Create dashboard user",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"username": {
"description": "Dashboard Username",
"example": "admin",
"maxLength": 100,
"type": "string"
},
"password": {
"description": "Dashboard Password",
"example": "public",
"maxLength": 100,
"type": "string"
},
"description": {
"description": "Dashboard User Description",
"example": "administrator",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"username": {
"description": "Dashboard Username",
"example": "admin",
"maxLength": 100,
"type": "string"
},
"description": {
"description": "Dashboard User Description",
"example": "administrator",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Dashboard"
]
}
},
"/authorization/sources/{type}/status": {
"get": {
"description": "Get a authorization source",
"parameters": [
{
"description": "Authorization type",
"in": "path",
"name": "type",
"required": true,
"schema": {
"enum": [
"http",
"mongodb",
"redis",
"built_in_database",
"mysql",
"postgresql",
"file"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"metrics_example": {
"summary": "Showing a typical metrics example",
"value": {
"metrics": {
"allow": 0,
"deny": 0,
"nomatch": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"total": 0
},
"node_metrics": [
{
"metrics": {
"allow": 0,
"deny": 0,
"nomatch": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"total": 0
},
"node": "emqx@127.0.0.1"
}
],
"node_resource_metrics": [
{
"metrics": {
"failed": 0,
"matched": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"success": 0
},
"node": "emqx@127.0.0.1"
}
],
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": "connected"
}
],
"resource_metrics": {
"failed": 0,
"matched": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"success": 0
},
"status": "connected"
}
}
},
"schema": {
"$ref": "#/components/schemas/authz.metrics_status_fields"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/listeners": {
"get": {
"description": "List all running node's listeners for the specified type.",
"parameters": [
{
"description": "Listener type",
"example": "tcp",
"in": "query",
"name": "type",
"required": false,
"schema": {
"enum": [
"tcp",
"ssl",
"ws",
"wss",
"quic"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": [
{
"acceptors": 16,
"bind": "0.0.0.0:1884",
"enable": true,
"id": "tcp:demo",
"name": "demo",
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 100,
"max_connections": 1024000,
"running": true
}
},
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 101,
"max_connections": 1024000,
"running": true
}
}
],
"number": 2,
"status": {
"current_connections": 201,
"max_connections": 2048000,
"running": true
},
"type": "tcp"
},
{
"acceptors": 32,
"bind": "0.0.0.0:1883",
"enable": true,
"id": "tcp:default",
"name": "default",
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 200,
"max_connections": "infinity",
"running": true
}
},
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 301,
"max_connections": "infinity",
"running": true
}
}
],
"number": 2,
"status": {
"current_connections": 501,
"max_connections": "infinity",
"running": true
},
"type": "tcp"
}
],
"schema": {
"items": {
"$ref": "#/components/schemas/listeners.listener_id_status"
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listeners"
]
},
"post": {
"description": "Create the specified listener on all nodes.",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"example": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "0.0.0.0:1884",
"current_connections": 10240,
"max_connections": 204800,
"mountpoint": "/",
"name": "demo",
"proxy_protocol": false,
"proxy_protocol_timeout": "3s",
"running": true,
"tcp_options": {
"active_n": 100,
"backlog": 1024,
"buffer": "4KB",
"high_watermark": "1MB",
"nodelay": false,
"reuseaddr": true,
"send_timeout": "15s",
"send_timeout_close": true
},
"type": "tcp",
"zone": "default"
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/listeners.quic_required_bind(with_name)"
},
{
"$ref": "#/components/schemas/listeners.wss_required_bind(with_name)"
},
{
"$ref": "#/components/schemas/listeners.ws_required_bind(with_name)"
},
{
"$ref": "#/components/schemas/listeners.ssl_required_bind(with_name)"
},
{
"$ref": "#/components/schemas/listeners.tcp_required_bind(with_name)"
}
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "0.0.0.0:1884",
"current_connections": 10240,
"id": "tcp:demo",
"max_connections": 204800,
"mountpoint": "/",
"proxy_protocol": false,
"proxy_protocol_timeout": "3s",
"running": true,
"tcp_options": {
"active_n": 100,
"backlog": 1024,
"buffer": "4KB",
"high_watermark": "1MB",
"nodelay": false,
"reuseaddr": true,
"send_timeout": "15s",
"send_timeout_close": true
},
"type": "tcp",
"zone": "default"
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/listeners.quic_required_bind"
},
{
"$ref": "#/components/schemas/listeners.wss_required_bind"
},
{
"$ref": "#/components/schemas/listeners.ws_required_bind"
},
{
"$ref": "#/components/schemas/listeners.ssl_required_bind"
},
{
"$ref": "#/components/schemas/listeners.tcp_required_bind"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_LISTENER_ID",
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listeners"
]
}
},
"/trace/{name}/download": {
"get": {
"description": "Download trace log by name",
"parameters": [
{
"$ref": "#/components/parameters/trace.name"
},
{
"$ref": "#/components/parameters/trace.node"
}
],
"responses": {
"200": {
"content": {
"application/octet-stream": {
"schema": {
"format": "binary",
"type": "string"
}
}
},
"description": "A trace zip file"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NODE_ERROR"
],
"type": "string"
},
"message": {
"description": "Node Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Trace Name Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Trace"
]
}
},
"/clients/{clientid}": {
"delete": {
"description": "Kick out client by client ID",
"parameters": [
{
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Kick out client successfully"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENTID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Clients"
]
},
"get": {
"description": "Get clients info by client ID",
"parameters": [
{
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_clients.client"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENTID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Clients"
]
}
},
"/gateways/{name}/authentication": {
"delete": {
"description": "Delete the authenticator of the specified gateway.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Delete the Gateway Authenticator",
"tags": [
"Gateway Authentication"
]
},
"get": {
"description": "Gets the configuration of the specified gateway authenticator.
Returns 404 when gateway or authentication is not enabled.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"204": {
"description": "Authenticator doesn't initiated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Get Authenticator Configuration",
"tags": [
"Gateway Authentication"
]
},
"post": {
"description": "Enables the authenticator for client authentication for the specified gateway.
When the authenticator is not configured or turned off, all client connections are assumed to be allowed.
Note: Only one authenticator is allowed to be enabled at a time in the gateway, rather than allowing multiple authenticators to be configured to form an authentication chain as in MQTT.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Create an Authenticator for a Gateway",
"tags": [
"Gateway Authentication"
]
},
"put": {
"description": "Update the configuration of the specified gateway authenticator, or disable the authenticator.",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Update Authenticator Configuration",
"tags": [
"Gateway Authentication"
]
}
},
"/clients/{clientid}/unsubscribe/bulk": {
"post": {
"description": "Unsubscribe",
"parameters": [
{
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_clients.unsubscribe"
},
"type": "array"
}
}
}
},
"responses": {
"204": {
"description": "Unsubscribe OK"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENTID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Clients"
]
}
},
"/clients/{clientid}/subscribe/bulk": {
"post": {
"description": "Subscribe",
"parameters": [
{
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_clients.subscribe"
},
"type": "array"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_subscriptions.subscription"
},
"type": "array"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENTID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Clients"
]
}
},
"/configs/alarm": {
"get": {
"description": "Get the sub-configurations under *alarm*",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.alarm"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *alarm*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.alarm"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.alarm"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/nodes/{node}": {
"get": {
"description": "Get node info",
"parameters": [
{
"$ref": "#/components/parameters/emqx_mgmt_api_nodes.node_name"
}
],
"responses": {
"200": {
"description": "Get node info successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_nodes.node_info"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"SOURCE_ERROR"
],
"type": "string"
},
"message": {
"description": "Node error",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Nodes"
]
}
},
"/configs/persistent_session_store": {
"get": {
"description": "Get the sub-configurations under *persistent_session_store*",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.persistent_session_store"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *persistent_session_store*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.persistent_session_store"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.persistent_session_store"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/gateways/coap/clients/{clientid}/request": {
"post": {
"description": "Send a CoAP request message to the client",
"parameters": [
{
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"token": {
"description": "Message token, can be empty",
"type": "string"
},
"method": {
"description": "Request method type",
"enum": [
"get",
"put",
"post",
"delete"
],
"type": "string"
},
"timeout": {
"description": "Timespan for response",
"example": "32s",
"type": "string"
},
"content_type": {
"description": "Payload type",
"enum": [
"text/plain",
"application/json",
"application/octet-stream"
],
"type": "string"
},
"payload": {
"description": "The content of the payload",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "Message ID",
"type": "integer"
},
"token": {
"description": "Message token, can be empty",
"type": "string"
},
"method": {
"description": "Response code",
"type": "string"
},
"payload": {
"description": "The content of the payload",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENT_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client not found error",
"type": "string"
}
},
"type": "object"
}
}
}
},
"504": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENT_NOT_RESPONSE"
],
"type": "string"
},
"message": {
"description": "Waiting for client response timeout",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Send a Request to a Client",
"tags": [
"CoAP Gateways"
]
}
},
"/listeners/{id}/stop": {
"post": {
"description": "Stop the listener on all nodes.",
"parameters": [
{
"$ref": "#/components/parameters/listeners.listener_id"
}
],
"responses": {
"200": {
"description": "Updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST",
"BAD_LISTENER_ID"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listeners"
]
}
},
"/topics": {
"get": {
"description": "Topics list",
"parameters": [
{
"description": "Topic Name",
"example": "",
"in": "query",
"name": "topic",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Node Name",
"example": "emqx@127.0.0.1",
"in": "query",
"name": "node",
"required": false,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_topics.topic"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/public.meta"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Topics"
]
}
},
"/authorization/sources": {
"get": {
"description": "List all authorization sources",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_authz_api_sources.sources"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"post": {
"description": "Add a new source",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_authz_api_schema.file"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.postgresql"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mysql"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.built_in_database"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_cluster"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_sentinel"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_single"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_sharded"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_rs"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_single"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.http_post"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.http_get"
}
]
}
}
}
},
"responses": {
"204": {
"description": "Authorization source created successfully"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/plugins": {
"get": {
"description": "List all install plugins.
Plugins are launched in top-down order.
Using `POST /plugins/{name}/move` to change the boot order.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/plugins.plugin"
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Plugins"
]
}
},
"/login": {
"post": {
"description": "Get Dashboard Auth Token.",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"username": {
"description": "Dashboard Username",
"example": "admin",
"maxLength": 100,
"type": "string"
},
"password": {
"description": "Dashboard Password",
"example": "public",
"maxLength": 100,
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"token": {
"description": "Dashboard Auth Token",
"type": "string"
},
"version": {
"description": "EMQX Version",
"example": "5.0.0",
"type": "string"
},
"license": {
"properties": {
"edition": {
"description": "EMQX License. opensource or enterprise",
"enum": [
"opensource",
"enterprise"
],
"example": "opensource",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_USERNAME_OR_PWD"
],
"type": "string"
},
"message": {
"description": "Login failed. Bad username or password",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [],
"summary": "Dashboard Auth",
"tags": [
"Dashboard"
]
}
},
"/bridges/{id}": {
"delete": {
"description": "Delete a bridge by Id",
"parameters": [
{
"description": "The bridge Id. Must be of format {type}:{name}",
"example": "webhook:webhook_example",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Bridge deleted"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"INVALID_ID"
],
"type": "string"
},
"message": {
"description": "Update bridge failed",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"FORBIDDEN_REQUEST"
],
"type": "string"
},
"message": {
"description": "Forbidden operation",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Bridge not found",
"type": "string"
}
},
"type": "object"
}
}
}
},
"503": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"SERVICE_UNAVAILABLE"
],
"type": "string"
},
"message": {
"description": "Service unavailable",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Delete Bridge",
"tags": [
"Bridges"
]
},
"get": {
"description": "Get a bridge by Id",
"parameters": [
{
"description": "The bridge Id. Must be of format {type}:{name}",
"example": "webhook:webhook_example",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"mqtt_example": {
"summary": "MQTT Bridge",
"value": {
"clean_start": true,
"egress": {
"local": {
"topic": "emqx/#"
},
"remote": {
"payload": "${payload}",
"qos": "${qos}",
"retain": false,
"topic": "from_emqx/${topic}"
}
},
"enable": true,
"ingress": {
"local": {
"payload": "${payload}",
"qos": "${qos}",
"retain": "${retain}",
"topic": "from_aws/${topic}"
},
"remote": {
"qos": 1,
"topic": "aws/#"
}
},
"keepalive": "300s",
"max_inflight": 100,
"mode": "cluster_shareload",
"name": "mqtt_example",
"password": "bar",
"proto_ver": "v4",
"resource_opts": {
"auto_restart_interval": "60s",
"health_check_interval": "15s",
"max_queue_bytes": 104857600,
"query_mode": "sync"
},
"retry_interval": "15s",
"server": "127.0.0.1:1883",
"ssl": {
"enable": false
},
"type": "mqtt",
"username": "foo"
}
},
"webhook_example": {
"summary": "WebHook",
"value": {
"body": "${payload}",
"connect_timeout": "15s",
"enable": true,
"enable_pipelining": 100,
"local_topic": "emqx_webhook/#",
"max_retries": 3,
"method": "post",
"name": "webhook_example",
"pool_size": 4,
"pool_type": "random",
"request_timeout": "15s",
"resource_opts": {
"async_inflight_window": 100,
"auto_restart_interval": 15000,
"health_check_interval": 15000,
"max_queue_bytes": 104857600,
"query_mode": "async",
"worker_pool_size": 1
},
"ssl": {
"enable": false
},
"type": "webhook",
"url": "http://localhost:9901/messages/${topic}"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/bridge_mqtt.get"
},
{
"$ref": "#/components/schemas/bridge_webhook.get"
}
]
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Bridge not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Get Bridge",
"tags": [
"Bridges"
]
},
"put": {
"description": "Update a bridge by Id",
"parameters": [
{
"description": "The bridge Id. Must be of format {type}:{name}",
"example": "webhook:webhook_example",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"mqtt_example": {
"summary": "MQTT Bridge",
"value": {
"clean_start": true,
"egress": {
"local": {
"topic": "emqx/#"
},
"remote": {
"payload": "${payload}",
"qos": "${qos}",
"retain": false,
"topic": "from_emqx/${topic}"
}
},
"enable": true,
"ingress": {
"local": {
"payload": "${payload}",
"qos": "${qos}",
"retain": "${retain}",
"topic": "from_aws/${topic}"
},
"remote": {
"qos": 1,
"topic": "aws/#"
}
},
"keepalive": "300s",
"max_inflight": 100,
"mode": "cluster_shareload",
"password": "bar",
"proto_ver": "v4",
"resource_opts": {
"auto_restart_interval": "60s",
"health_check_interval": "15s",
"max_queue_bytes": 104857600,
"query_mode": "sync"
},
"retry_interval": "15s",
"server": "127.0.0.1:1883",
"ssl": {
"enable": false
},
"username": "foo"
}
},
"webhook_example": {
"summary": "WebHook",
"value": {
"body": "${payload}",
"connect_timeout": "15s",
"enable": true,
"enable_pipelining": 100,
"local_topic": "emqx_webhook/#",
"max_retries": 3,
"method": "post",
"pool_size": 4,
"pool_type": "random",
"request_timeout": "15s",
"resource_opts": {
"async_inflight_window": 100,
"auto_restart_interval": 15000,
"health_check_interval": 15000,
"max_queue_bytes": 104857600,
"query_mode": "async",
"worker_pool_size": 1
},
"ssl": {
"enable": false
},
"url": "http://localhost:9901/messages/${topic}"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/bridge_mqtt.put"
},
{
"$ref": "#/components/schemas/bridge_webhook.put"
}
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"mqtt_example": {
"summary": "MQTT Bridge",
"value": {
"clean_start": true,
"egress": {
"local": {
"topic": "emqx/#"
},
"remote": {
"payload": "${payload}",
"qos": "${qos}",
"retain": false,
"topic": "from_emqx/${topic}"
}
},
"enable": true,
"ingress": {
"local": {
"payload": "${payload}",
"qos": "${qos}",
"retain": "${retain}",
"topic": "from_aws/${topic}"
},
"remote": {
"qos": 1,
"topic": "aws/#"
}
},
"keepalive": "300s",
"max_inflight": 100,
"mode": "cluster_shareload",
"name": "mqtt_example",
"password": "bar",
"proto_ver": "v4",
"resource_opts": {
"auto_restart_interval": "60s",
"health_check_interval": "15s",
"max_queue_bytes": 104857600,
"query_mode": "sync"
},
"retry_interval": "15s",
"server": "127.0.0.1:1883",
"ssl": {
"enable": false
},
"type": "mqtt",
"username": "foo"
}
},
"webhook_example": {
"summary": "WebHook",
"value": {
"body": "${payload}",
"connect_timeout": "15s",
"enable": true,
"enable_pipelining": 100,
"local_topic": "emqx_webhook/#",
"max_retries": 3,
"method": "post",
"name": "webhook_example",
"pool_size": 4,
"pool_type": "random",
"request_timeout": "15s",
"resource_opts": {
"async_inflight_window": 100,
"auto_restart_interval": 15000,
"health_check_interval": 15000,
"max_queue_bytes": 104857600,
"query_mode": "async",
"worker_pool_size": 1
},
"ssl": {
"enable": false
},
"type": "webhook",
"url": "http://localhost:9901/messages/${topic}"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/bridge_mqtt.get"
},
{
"$ref": "#/components/schemas/bridge_webhook.get"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST",
"INVALID_ID"
],
"type": "string"
},
"message": {
"description": "Update bridge failed",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Bridge not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Update Bridge",
"tags": [
"Bridges"
]
}
},
"/configs/dashboard": {
"get": {
"description": "Get the sub-configurations under *dashboard*",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dashboard.dashboard"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *dashboard*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dashboard.dashboard"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dashboard.dashboard"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/gateways/{name}/clients/{clientid}/subscriptions": {
"get": {
"description": "Get the gateway client subscriptions",
"parameters": [
{
"description": "Client ID",
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Gateway Name",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"general_subscription_list": {
"summary": "A General Subscription List",
"value": [
{
"nl": 0,
"qos": 1,
"rap": 0,
"rh": 0,
"topic": "test/topic"
}
]
},
"stomp_subscription_list": {
"summary": "The Stomp Subscription List",
"value": [
"example_stomp_subscription"
]
}
},
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_gateway_api_clients.subscription"
},
"type": "array"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "List Client's Subscription",
"tags": [
"Gateway Clients"
]
},
"post": {
"description": "Create a subscription membership",
"parameters": [
{
"description": "Client ID",
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Gateway Name",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"general_subscription": {
"summary": "A General Subscription",
"value": {
"nl": 0,
"qos": 1,
"rap": 0,
"rh": 0,
"topic": "test/topic"
}
},
"stomp_subscription": {
"summary": "A Stomp Subscription",
"value": {
"nl": 0,
"qos": 1,
"rap": 0,
"rh": 0,
"sub_props": {
"subid": "10"
},
"topic": "stomp/topic"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_gateway_api_clients.subscription"
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"examples": {
"general_subscription": {
"summary": "A General Subscription",
"value": {
"nl": 0,
"qos": 1,
"rap": 0,
"rh": 0,
"topic": "test/topic"
}
},
"stomp_subscription": {
"summary": "A Stomp Subscription",
"value": {
"nl": 0,
"qos": 1,
"rap": 0,
"rh": 0,
"sub_props": {
"subid": "10"
},
"topic": "stomp/topic"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_gateway_api_clients.subscription"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Add Subscription for Client",
"tags": [
"Gateway Clients"
]
}
},
"/cluster/{node}/invite": {
"put": {
"description": "Invite node to cluster",
"parameters": [
{
"$ref": "#/components/parameters/cluster.node"
}
],
"responses": {
"200": {
"description": "ok"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Cluster"
]
}
},
"/listeners/{listener_id}/authentication/{id}/position/{position}": {
"put": {
"description": "Move authenticator in listener authentication chain.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Position of authenticator in chain. Possible values are 'front', 'rear', 'before:{other_authenticator}', 'after:{other_authenticator}'.",
"example": "before:password_based:built_in_database",
"in": "path",
"name": "position",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Authenticator moved"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
}
},
"/configs/node": {
"get": {
"description": "Get the sub-configurations under *node*",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_conf_schema.node"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *node*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_conf_schema.node"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_conf_schema.node"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/configs/zones": {
"get": {
"description": "Get the sub-configurations under *zones*",
"parameters": [],
"responses": {
"200": {
"description": "A zone is a set of configs grouped by the zone name.
For flexible configuration mapping, the name can be set to a listener's zone config.
NOTE: A built-in zone named default is auto created and can not be deleted.
",
"content": {
"application/json": {
"schema": {
"properties": {
"$name": {
"$ref": "#/components/schemas/broker.zone"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *zones*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"$name": {
"$ref": "#/components/schemas/broker.zone"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "A zone is a set of configs grouped by the zone name.
For flexible configuration mapping, the name can be set to a listener's zone config.
NOTE: A built-in zone named default is auto created and can not be deleted.
",
"content": {
"application/json": {
"schema": {
"properties": {
"$name": {
"$ref": "#/components/schemas/broker.zone"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/mqtt/retainer/messages": {
"get": {
"description": "List retained messages.",
"parameters": [
{
"description": "Page number of the results to fetch.",
"example": 1,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"minimum": 1,
"type": "integer"
}
},
{
"description": "Results per page(max 1000)",
"example": 50,
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"description": "Retained messages list.",
"items": {
"$ref": "#/components/schemas/retainer.message_summary"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/public.meta"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Unsupported backend.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Retainer"
]
}
},
"/plugins/{name}/move": {
"post": {
"description": "Setting the boot order of plugins.",
"parameters": [
{
"$ref": "#/components/parameters/plugins.name"
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"move_to_after": {
"summary": "move plugin after other plugins",
"value": {
"position": "after:emqx_plugin_demo-5.1-rc.2"
}
},
"move_to_before": {
"summary": "move plugin before other plugins",
"value": {
"position": "before:emqx_plugin_demo-5.1-rc.2"
}
},
"move_to_front": {
"summary": "move plugin on the front",
"value": {
"position": "front"
}
},
"move_to_rear": {
"summary": "move plugin on the rear",
"value": {
"position": "rear"
}
}
},
"schema": {
"$ref": "#/components/schemas/plugins.position"
}
}
}
},
"responses": {
"200": {
"description": "OK"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Plugins"
]
}
},
"/configs/broker": {
"get": {
"description": "Get the sub-configurations under *broker*",
"parameters": [],
"responses": {
"200": {
"description": "Message broker options.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.broker"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *broker*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.broker"
}
}
}
},
"responses": {
"200": {
"description": "Message broker options.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.broker"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/statsd": {
"get": {
"description": "List the configuration of StatsD metrics collection and push service.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"enable": true,
"flush_time_interval": "30s",
"sample_time_interval": "30s",
"server": "127.0.0.1:8125",
"tags": {}
},
"schema": {
"$ref": "#/components/schemas/statsd.statsd"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Monitor"
]
},
"put": {
"description": "Update the configuration of StatsD metrics collection and push service.",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"example": {
"enable": true,
"flush_time_interval": "30s",
"sample_time_interval": "30s",
"server": "127.0.0.1:8125",
"tags": {}
},
"schema": {
"$ref": "#/components/schemas/statsd.statsd"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"enable": true,
"flush_time_interval": "30s",
"sample_time_interval": "30s",
"server": "127.0.0.1:8125",
"tags": {}
},
"schema": {
"$ref": "#/components/schemas/statsd.statsd"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Monitor"
]
}
},
"/alarms": {
"delete": {
"description": "Remove all historical alarms.",
"parameters": [],
"responses": {
"204": {
"description": "Historical alarms have been cleared successfully."
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Alarms"
]
},
"get": {
"description": "List currently activated alarms or historical alarms, determined by query parameters.",
"parameters": [
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
},
{
"description": "It is used to specify the alarm type of the query.
When true, it returns the currently activated alarm,
and when it is false, it returns the historical alarm.
The default is false.",
"in": "query",
"name": "activated",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_alarms.alarm"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/public.meta"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Alarms"
]
}
},
"/authorization/sources/built_in_database/rules/users/{username}": {
"delete": {
"description": "Delete rule for 'username'",
"parameters": [
{
"$ref": "#/components/parameters/emqx_authz_api_mnesia.username"
}
],
"responses": {
"204": {
"description": "Deleted"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad username",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Username Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"get": {
"description": "Get rule for 'username'",
"parameters": [
{
"$ref": "#/components/parameters/emqx_authz_api_mnesia.username"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"password_based:built_in_database": {
"summary": "Username",
"value": {
"rules": [
{
"action": "publish",
"permission": "allow",
"topic": "test/toopic/1"
},
{
"action": "subscribe",
"permission": "allow",
"topic": "test/toopic/2"
},
{
"action": "all",
"permission": "deny",
"topic": "eq test/#"
}
],
"username": "user1"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rules_for_username"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"put": {
"description": "Set rule for 'username'",
"parameters": [
{
"$ref": "#/components/parameters/emqx_authz_api_mnesia.username"
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"password_based:built_in_database": {
"summary": "Username",
"value": {
"rules": [
{
"action": "publish",
"permission": "allow",
"topic": "test/toopic/1"
},
{
"action": "subscribe",
"permission": "allow",
"topic": "test/toopic/2"
},
{
"action": "all",
"permission": "deny",
"topic": "eq test/#"
}
],
"username": "user1"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rules_for_username"
}
}
}
},
"responses": {
"204": {
"description": "Updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad username or bad rule schema",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/subscriptions": {
"get": {
"description": "List subscriptions",
"parameters": [
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
},
{
"description": "Node name",
"example": "emqx@127.0.0.1",
"in": "query",
"name": "node",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Client ID",
"in": "query",
"name": "clientid",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "QoS",
"in": "query",
"name": "qos",
"required": false,
"schema": {
"example": 0,
"maximum": 2,
"minimum": 0,
"type": "integer"
}
},
{
"description": "Topic, url encoding",
"in": "query",
"name": "topic",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Match topic string, url encoding",
"in": "query",
"name": "match_topic",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Shared subscription group name",
"in": "query",
"name": "share_group",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_subscriptions.subscription"
},
"type": "array"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"INVALID_PARAMETER"
],
"type": "string"
},
"message": {
"description": "Invalid parameter",
"type": "string"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NODE_DOWN"
],
"type": "string"
},
"message": {
"description": "Bad RPC",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Subscriptions"
]
}
},
"/error_codes": {
"get": {
"description": "API Error Codes",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/dashboard.error_code"
},
"type": "array"
}
}
}
}
},
"security": [],
"tags": [
"Error Codes"
]
}
},
"/authorization/sources/built_in_database/rules": {
"delete": {
"description": "Delete all rules for all 'users', 'clients' and 'all'",
"parameters": [],
"responses": {
"204": {
"description": "Deleted"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/listeners/{listener_id}/authentication/{id}/users/{user_id}": {
"delete": {
"description": "Delete user in authenticator in listener authentication chain.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID.",
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "User deleted"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
},
"get": {
"description": "Get user from authenticator in listener authentication chain.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID.",
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
},
"put": {
"description": "Update user in authenticator in listener authentication chain.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID.",
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"regular_user": {
"summary": "Update regular user",
"value": {
"password": "newsecret"
}
},
"super_user": {
"summary": "Update user and promote to superuser",
"value": {
"is_superuser": true,
"password": "newsecret"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.request_user_update"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
}
},
"/authorization/sources/{type}/move": {
"post": {
"description": "Change the exection order of sources",
"parameters": [
{
"description": "Authorization type",
"in": "path",
"name": "type",
"required": true,
"schema": {
"enum": [
"http",
"mongodb",
"redis",
"built_in_database",
"mysql",
"postgresql",
"file"
],
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"front": {
"summary": "front example",
"value": {
"position": "front"
}
},
"rear": {
"summary": "rear example",
"value": {
"position": "rear"
}
},
"relative_after": {
"summary": "relative example",
"value": {
"position": "after:file"
}
},
"relative_before": {
"summary": "relative example",
"value": {
"position": "before:file"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authz_api_schema.position"
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/listeners/{listener_id}/authentication/{id}/import_users": {
"post": {
"description": "Import users into authenticator in listener authentication chain.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"properties": {
"filename": {
"format": "binary",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"204": {
"description": "Users imported"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
}
},
"/telemetry/data": {
"get": {
"description": "Get telemetry data",
"parameters": [],
"responses": {
"200": {
"description": "Get telemetry data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_telemetry_api.telemetry"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Telemetry is not enabled",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Telemetry"
]
}
},
"/gateways/{name}/listeners/{id}/authentication/users/{uid}": {
"delete": {
"description": "Delete the user for the gateway authenticator (only supports built_in_database)",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID",
"example": "",
"in": "path",
"name": "uid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Delete User",
"tags": [
"Gateway Listeners"
]
},
"get": {
"description": "Get user info from the gateway authenticator (only supports built_in_database)",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID",
"example": "",
"in": "path",
"name": "uid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Get User Info",
"tags": [
"Gateway Listeners"
]
},
"put": {
"description": "Update the user info for the gateway authenticator (only supports built_in_database)",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID",
"example": "",
"in": "path",
"name": "uid",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"regular_user": {
"summary": "Update regular user",
"value": {
"password": "newsecret"
}
},
"super_user": {
"summary": "Update user and promote to superuser",
"value": {
"is_superuser": true,
"password": "newsecret"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.request_user_update"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Update User Info",
"tags": [
"Gateway Listeners"
]
}
},
"/authentication": {
"get": {
"description": "List authenticators for global authentication.",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": [
{
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
},
{
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
},
{
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
},
{
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
},
{
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
],
"schema": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
},
"post": {
"description": "Create authenticator for global authentication.",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"ALREADY_EXISTS"
],
"type": "string"
},
"message": {
"description": "ALREADY_EXISTS",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authentication"
]
}
},
"/clients/{clientid}/subscribe": {
"post": {
"description": "Subscribe",
"parameters": [
{
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_clients.subscribe"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_subscriptions.subscription"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENTID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Clients"
]
}
},
"/trace": {
"delete": {
"description": "Clear all traces",
"parameters": [],
"responses": {
"204": {
"description": "No Content"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Trace"
]
},
"get": {
"description": "List all trace",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/trace.trace"
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Trace"
]
},
"post": {
"description": "Create new trace",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"type",
"name"
],
"properties": {
"name": {
"description": "Unique and format by [a-zA-Z0-9-_]",
"example": "EMQX-TRACE-1",
"type": "string"
},
"type": {
"description": "Filter type",
"enum": [
"clientid",
"topic",
"ip_address"
],
"example": "clientid",
"type": "string"
},
"topic": {
"description": "support mqtt wildcard topic.",
"example": "/dev/#",
"type": "string"
},
"clientid": {
"description": "mqtt clientid.",
"example": "dev-001",
"type": "string"
},
"ip_address": {
"description": "client ip address",
"example": "127.0.0.1",
"type": "string"
},
"start_at": {
"description": "rfc3339 timestamp or epoch second",
"example": "2021-11-04T18:17:38+08:00",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"end_at": {
"description": "rfc3339 timestamp or epoch second",
"example": "2021-11-05T18:17:38+08:00",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/trace.trace"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"INVALID_PARAMS"
],
"type": "string"
},
"message": {
"description": "invalid trace params",
"type": "string"
}
},
"type": "object"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"ALREADY_EXISTS",
"DUPLICATE_CONDITION"
],
"type": "string"
},
"message": {
"description": "trace already exists",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Trace"
]
}
},
"/exhooks/{name}/move": {
"post": {
"description": "Move the server.
NOTE: The position should be \"front | rear | before:{name} | after:{name}",
"parameters": [
{
"description": "The Exhook server name",
"example": "default",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"front": {
"summary": "absolute position 'front'",
"value": {
"position": "front"
}
},
"rear": {
"summary": "absolute position 'rear'",
"value": {
"position": "rear"
}
},
"related_after": {
"summary": "relative position 'after'",
"value": {
"position": "after:default"
}
},
"related_before": {
"summary": "relative position 'before'",
"value": {
"position": "before:default"
}
}
},
"schema": {
"$ref": "#/components/schemas/exhook.move_req"
}
}
}
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_RPC"
],
"type": "string"
},
"message": {
"description": "Bad RPC",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"ExHook"
]
}
},
"/slow_subscriptions/settings": {
"get": {
"description": "View slow subs settings",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/slow_subs.slow_subs"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Slow Subscriptions"
]
},
"put": {
"description": "Update slow subs settings",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/slow_subs.slow_subs"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/slow_subs.slow_subs"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Slow Subscriptions"
]
}
},
"/mqtt/topic_metrics": {
"get": {
"description": "List Topic metrics",
"parameters": [],
"responses": {
"200": {
"description": "List Topic metrics",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_topic_metrics_api.topic_metrics"
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
},
"post": {
"description": "Create Topic metrics",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"topic"
],
"properties": {
"topic": {
"description": "Raw topic string",
"example": "testtopic/1",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"204": {
"description": "Create Topic metrics"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST",
"BAD_TOPIC"
],
"type": "string"
},
"message": {
"description": "Bad Request. Already exists or bad topic name",
"type": "string"
}
},
"type": "object"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"EXCEED_LIMIT"
],
"type": "string"
},
"message": {
"description": "Conflict. Topic metrics exceeded max limit 512",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
},
"put": {
"description": "Reset telemetry status",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"examples": {
"reset_all_topic_metrics": {
"summary": "reset_all_topic_metrics",
"value": {
"action": "reset"
}
},
"reset_specific_one_topic_metrics": {
"summary": "reset_specific_one_topic_metrics",
"value": {
"action": "reset",
"topic": "testtopic/1"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_topic_metrics_api.reset"
}
}
}
},
"responses": {
"204": {
"description": "Reset telemetry status"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"TOPIC_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found. Topic metrics not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
}
},
"/configs/trace": {
"get": {
"description": "Get the sub-configurations under *trace*",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.trace"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *trace*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.trace"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/broker.trace"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/error_codes/{code}": {
"get": {
"description": "API Error Codes",
"parameters": [
{
"description": "API Error Codes",
"example": "BAD_USERNAME_OR_PWD",
"in": "path",
"name": "code",
"required": true,
"schema": {
"enum": [
"BAD_USERNAME_OR_PWD",
"BAD_API_KEY_OR_SECRET",
"BAD_REQUEST",
"NOT_MATCH",
"ALREADY_EXISTS",
"BAD_CONFIG_SCHEMA",
"BAD_LISTENER_ID",
"BAD_NODE_NAME",
"BAD_RPC",
"BAD_TOPIC",
"EXCEED_LIMIT",
"INVALID_PARAMETER",
"CONFLICT",
"NO_DEFAULT_VALUE",
"DEPENDENCY_EXISTS",
"MESSAGE_ID_SCHEMA_ERROR",
"INVALID_ID",
"MESSAGE_ID_NOT_FOUND",
"NOT_FOUND",
"CLIENTID_NOT_FOUND",
"CLIENT_NOT_FOUND",
"RESOURCE_NOT_FOUND",
"TOPIC_NOT_FOUND",
"USER_NOT_FOUND",
"INTERNAL_ERROR",
"SERVICE_UNAVAILABLE",
"SOURCE_ERROR",
"UPDATE_FAILED",
"REST_FAILED",
"CLIENT_NOT_RESPONSE"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dashboard.error_code"
}
}
}
}
},
"security": [],
"tags": [
"Error Codes"
]
}
},
"/bridges/{id}/{operation}": {
"post": {
"description": "Stop/Restart bridges on all nodes in the cluster.",
"parameters": [
{
"description": "The bridge Id. Must be of format {type}:{name}",
"example": "webhook:webhook_example",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Operations can be one of: stop, restart",
"example": "restart",
"in": "path",
"name": "operation",
"required": true,
"schema": {
"enum": [
"stop",
"restart"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Operation success"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"INVALID_ID"
],
"type": "string"
},
"message": {
"description": "Bad bridge ID",
"type": "string"
}
},
"type": "object"
}
}
}
},
"503": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"SERVICE_UNAVAILABLE"
],
"type": "string"
},
"message": {
"description": "Service unavailable",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Stop or Restart Bridge",
"tags": [
"Bridges"
]
}
},
"/gateways/{name}/clients/{clientid}/subscriptions/{topic}": {
"delete": {
"description": "Delete a subscriptions membership",
"parameters": [
{
"description": "Topic Filter/Name",
"in": "path",
"name": "topic",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Client ID",
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Gateway Name",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Unsubscribed"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Delete Client's Subscription",
"tags": [
"Gateway Clients"
]
}
},
"/mqtt/delayed/messages": {
"get": {
"description": "List delayed messages",
"parameters": [
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/emqx_delayed_api.message"
},
"type": "array"
},
"meta": {
"properties": {
"page": {
"description": "View page",
"minimum": 1,
"type": "integer"
},
"limit": {
"description": "Page limit",
"minimum": 1,
"type": "integer"
},
"count": {
"description": "Count of delayed messages",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"MQTT"
]
}
},
"/users/{username}": {
"delete": {
"description": "Delete dashboard user",
"parameters": [
{
"description": "Dashboard Username",
"example": "admin",
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Delete User successfully"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST",
"NOT_ALLOWED"
],
"type": "string"
},
"message": {
"description": "Login failed. Bad username or password",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"USER_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Dashboard user not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Dashboard"
]
},
"put": {
"description": "Update dashboard user description",
"parameters": [
{
"description": "Dashboard Username",
"example": "admin",
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"description": {
"description": "Dashboard User Description",
"example": "administrator",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"username": {
"description": "Dashboard Username",
"example": "admin",
"maxLength": 100,
"type": "string"
},
"description": {
"description": "Dashboard User Description",
"example": "administrator",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"USER_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Dashboard user not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Dashboard"
]
}
},
"/exhooks": {
"get": {
"description": "List all servers",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/exhook.detail_server_info"
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"ExHook"
]
},
"post": {
"description": "Add a server",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"example": {
"auto_reconnect": "60s",
"enable": true,
"failed_action": "deny",
"name": "default",
"pool_size": 8,
"request_timeout": "5s",
"ssl": {
"cacertfile": "/etc/emqx/certs/cacert.pem",
"certfile": "/etc/emqx/certs/cert.pem",
"enable": false,
"keyfile": "/etc/emqx/certs/key.pem"
},
"url": "http://127.0.0.1:8081"
},
"schema": {
"$ref": "#/components/schemas/exhook.server_config"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/exhook.detail_server_info"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Already exists",
"type": "string"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_RPC"
],
"type": "string"
},
"message": {
"description": "Bad RPC",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"ExHook"
]
}
},
"/gateways/lwm2m/clients/{clientid}/lookup": {
"get": {
"description": "Look up a resource",
"parameters": [
{
"example": "urn:oma:lwm2m:oma:2",
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
},
{
"example": "/3/0/7",
"in": "query",
"name": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"example": "discover",
"in": "query",
"name": "action",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"clientid": {
"example": "urn:oma:lwm2m:oma:2",
"type": "string"
},
"path": {
"example": "/3/0/7",
"type": "string"
},
"action": {
"example": "discover",
"type": "string"
},
"codeMsg": {
"example": "reply_not_received",
"type": "string"
},
"content": {
"items": {
"$ref": "#/components/schemas/lwm2m.resource"
},
"type": "array"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENT_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "List Client's Resources",
"tags": [
"LwM2M Gateways"
]
}
},
"/rules/{id}/metrics": {
"get": {
"description": "Get a rule's metrics by given Id",
"parameters": [
{
"example": "my_rule_id",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_rule_api_schema.rule_metrics"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Rule not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Get a Rule's Metrics",
"tags": [
"Rules"
]
}
},
"/slow_subscriptions": {
"delete": {
"description": "Clear current data and re count slow topic",
"parameters": [],
"responses": {
"204": {
"description": "No Content"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Slow Subscriptions"
]
},
"get": {
"description": "View slow topics statistics record data",
"parameters": [
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/slow_subscribers_statistics.record"
},
"type": "array"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Slow Subscriptions"
]
}
},
"/gateways/{name}": {
"get": {
"description": "Get the gateway configurations",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"coap_gateway": {
"summary": "A simple CoAP gateway configs",
"value": {
"connection_required": false,
"enable": true,
"enable_stats": true,
"heartbeat": "30s",
"idle_timeout": "30s",
"listeners": [
{
"bind": "5683",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "default",
"type": "udp"
}
],
"mountpoint": "coap/",
"name": "coap",
"notify_type": "qos",
"publish_qos": "coap",
"subscribe_qos": "coap"
}
},
"exproto_gateway": {
"summary": "A simple ExProto gateway configs",
"value": {
"enable": true,
"enable_stats": true,
"handler": {
"address": "http://127.0.0.1:9001"
},
"idle_timeout": "30s",
"listeners": [
{
"bind": "7993",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "default",
"type": "tcp"
}
],
"mountpoint": "exproto/",
"name": "exproto",
"server": {
"bind": "9100"
}
}
},
"lwm2m_gateway": {
"summary": "A simple LwM2M gateway configs",
"value": {
"auto_observe": false,
"enable": true,
"enable_stats": true,
"idle_timeout": "30s",
"lifetime_max": "86400s",
"lifetime_min": "1s",
"listeners": [
{
"bind": "5783",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "default",
"type": "udp"
}
],
"mountpoint": "lwm2m/",
"name": "lwm2m",
"qmode_time_window": "22s",
"translators": {
"command": {
"topic": "dn/#"
},
"notify": {
"topic": "up/notify"
},
"register": {
"topic": "up/resp"
},
"response": {
"topic": "up/resp"
},
"update": {
"topic": "up/resp"
}
},
"update_msg_publish_condition": "always",
"xml_dir": "/etc/emqx/lwm2m_xml"
}
},
"mqttsn_gateway": {
"summary": "A simple MQTT-SN gateway configs",
"value": {
"broadcast": true,
"enable": true,
"enable_qos3": true,
"enable_stats": true,
"gateway_id": 1,
"idle_timeout": "30s",
"listeners": [
{
"bind": "1884",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "default",
"type": "udp"
}
],
"mountpoint": "mqttsn/",
"name": "mqttsn",
"predefined": [
{
"id": "1001",
"topic": "pred/1001"
},
{
"id": "1002",
"topic": "pred/1002"
}
]
}
},
"stomp_gateway": {
"summary": "A simple STOMP gateway configs",
"value": {
"enable": true,
"enable_stats": true,
"frame": {
"max_body_length": 65535,
"max_headers": 10,
"max_headers_length": 1024
},
"idle_timeout": "30s",
"listeners": [
{
"bind": "61613",
"max_conn_rate": 1000,
"max_connections": 1024000,
"name": "default",
"type": "tcp"
}
],
"mountpoint": "stomp/",
"name": "stomp"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.exproto"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.lwm2m"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.coap"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.mqttsn"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.stomp"
}
]
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Get the Gateway",
"tags": [
"Gateways"
]
},
"put": {
"description": "Update the gateway basic configurations and running status.
Note: The Authentication and Listener configurations should be updated by other special APIs. ",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"coap_gateway": {
"summary": "A simple CoAP gateway configs",
"value": {
"connection_required": false,
"enable": true,
"enable_stats": true,
"heartbeat": "30s",
"idle_timeout": "30s",
"mountpoint": "coap2/",
"notify_type": "qos",
"publish_qos": "coap",
"subscribe_qos": "coap"
}
},
"exproto_gateway": {
"summary": "A simple ExProto gateway configs",
"value": {
"enable": true,
"enable_stats": true,
"handler": {
"address": "http://127.0.0.1:9001"
},
"idle_timeout": "30s",
"mountpoint": "exproto2/",
"server": {
"bind": "9100"
}
}
},
"lwm2m_gateway": {
"summary": "A simple LwM2M gateway configs",
"value": {
"auto_observe": false,
"enable": true,
"enable_stats": true,
"idle_timeout": "30s",
"lifetime_max": "86400s",
"lifetime_min": "1s",
"mountpoint": "lwm2m2/",
"qmode_time_window": "22s",
"translators": {
"command": {
"topic": "dn/#"
},
"notify": {
"topic": "up/notify"
},
"register": {
"topic": "up/resp"
},
"response": {
"topic": "up/resp"
},
"update": {
"topic": "up/resp"
}
},
"update_msg_publish_condition": "always",
"xml_dir": "/etc/emqx/lwm2m_xml"
}
},
"mqttsn_gateway": {
"summary": "A simple MQTT-SN gateway configs",
"value": {
"broadcast": true,
"enable": true,
"enable_qos3": false,
"enable_stats": true,
"gateway_id": 1,
"idle_timeout": "30s",
"mountpoint": "mqttsn2/",
"predefined": [
{
"id": "1003",
"topic": "pred/1003"
}
]
}
},
"stomp_gateway": {
"summary": "A simple STOMP gateway configs",
"value": {
"enable": true,
"enable_stats": true,
"frame": {
"max_body_length": 655350,
"max_headers": 100,
"max_headers_length": 10240
},
"idle_timeout": "30s",
"mountpoint": "stomp2/"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_gateway_api.update_exproto"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.update_lwm2m"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.update_coap"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.update_mqttsn"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.update_stomp"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.exproto"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.lwm2m"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.coap"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.mqttsn"
},
{
"$ref": "#/components/schemas/emqx_gateway_api.stomp"
}
]
}
}
}
},
"responses": {
"204": {
"description": "Gateway configuration updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Load or update the gateway confs",
"tags": [
"Gateways"
]
}
},
"/nodes": {
"get": {
"description": "List EMQX nodes",
"parameters": [],
"responses": {
"200": {
"description": "List all EMQX nodes",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_nodes.node_info"
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Nodes"
]
}
},
"/authorization/sources/{type}": {
"delete": {
"description": "Delete source",
"parameters": [
{
"description": "Authorization type",
"in": "path",
"name": "type",
"required": true,
"schema": {
"enum": [
"http",
"mongodb",
"redis",
"built_in_database",
"mysql",
"postgresql",
"file"
],
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted successfully"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"get": {
"description": "Get a authorization source",
"parameters": [
{
"description": "Authorization type",
"in": "path",
"name": "type",
"required": true,
"schema": {
"enum": [
"http",
"mongodb",
"redis",
"built_in_database",
"mysql",
"postgresql",
"file"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Authorization source",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_authz_api_schema.file"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.postgresql"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mysql"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.built_in_database"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_cluster"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_sentinel"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_single"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_sharded"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_rs"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_single"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.http_post"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.http_get"
}
]
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"put": {
"description": "Update source",
"parameters": [
{
"description": "Authorization type",
"in": "path",
"name": "type",
"required": true,
"schema": {
"enum": [
"http",
"mongodb",
"redis",
"built_in_database",
"mysql",
"postgresql",
"file"
],
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/emqx_authz_api_schema.file"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.postgresql"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mysql"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.built_in_database"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_cluster"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_sentinel"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.redis_single"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_sharded"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_rs"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.mongo_single"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.http_post"
},
{
"$ref": "#/components/schemas/emqx_authz_api_schema.http_get"
}
]
}
}
}
},
"responses": {
"204": {
"description": "Authorization source updated successfully"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/gateways/{name}/authentication/import_users": {
"post": {
"description": "Import users into the gateway authenticator (only supports built_in_database)",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"properties": {
"filename": {
"format": "binary",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"204": {
"description": "Imported"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Import Users",
"tags": [
"Gateway Authentication"
]
}
},
"/api_key": {
"get": {
"description": "Return api_key list",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"description": "Unique and format by [a-zA-Z0-9-_]",
"example": "EMQX-API-KEY-1",
"type": "string"
},
"api_key": {
"description": "TODO:uses HMAC-SHA256 for signing.",
"example": "a4697a5c75a769f6",
"type": "string"
},
"expired_at": {
"default": "infinity",
"description": "No longer valid datetime",
"example": "2021-12-05T02:01:34.186Z",
"oneOf": [
{
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"created_at": {
"description": "ApiKey create datetime",
"example": "2021-12-01T00:00:00.000Z",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"desc": {
"example": "Note",
"type": "string"
},
"enable": {
"description": "Enable/Disable",
"type": "boolean"
},
"expired": {
"description": "Expired",
"type": "boolean"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"API Keys"
]
},
"post": {
"description": "Create new api_key",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"description": "Unique and format by [a-zA-Z0-9-_]",
"example": "EMQX-API-KEY-1",
"type": "string"
},
"expired_at": {
"default": "infinity",
"description": "No longer valid datetime",
"example": "2021-12-05T02:01:34.186Z",
"oneOf": [
{
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"desc": {
"example": "Note",
"type": "string"
},
"enable": {
"description": "Enable/Disable",
"type": "boolean"
},
"expired": {
"description": "Expired",
"type": "boolean"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/api_key.app"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"API Keys"
]
}
},
"/listeners/{id}/start": {
"post": {
"description": "Start the listener on all nodes.",
"parameters": [
{
"$ref": "#/components/parameters/listeners.listener_id"
}
],
"responses": {
"200": {
"description": "Updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST",
"BAD_LISTENER_ID"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listeners"
]
}
},
"/banned": {
"get": {
"description": "List all currently banned client IDs, usernames and IP addresses.",
"parameters": [
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_banned.ban"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/public.meta"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Banned"
]
},
"post": {
"description": "Add a client ID, username or IP address to the blacklist.",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_banned.ban"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_banned.ban"
},
"type": "array"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"ALREADY_EXISTS",
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request, possibly due to wrong parameters or the existence of a banned object.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Banned"
]
}
},
"/trace/{name}/log": {
"get": {
"description": "view trace log",
"parameters": [
{
"$ref": "#/components/parameters/trace.name"
},
{
"$ref": "#/components/parameters/trace.bytes"
},
{
"$ref": "#/components/parameters/trace.position"
},
{
"$ref": "#/components/parameters/trace.node"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"example": "TEXT-LOG-ITEMS",
"type": "string"
},
"meta": {
"properties": {
"bytes": {
"default": 1000,
"description": "Maximum number of bytes to store in request",
"type": "integer"
},
"position": {
"default": 0,
"description": "Offset from the current trace position.",
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NODE_ERROR"
],
"type": "string"
},
"message": {
"description": "Trace Log Failed",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Trace Name Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Trace"
]
}
},
"/trace/{name}": {
"delete": {
"description": "Delete specified trace",
"parameters": [
{
"$ref": "#/components/parameters/trace.name"
}
],
"responses": {
"204": {
"description": "Delete successfully"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Trace Name Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Trace"
]
}
},
"/trace/{name}/stop": {
"put": {
"description": "Stop trace by name",
"parameters": [
{
"$ref": "#/components/parameters/trace.name"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/trace.trace"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Trace Name Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Trace"
]
}
},
"/listeners/{id}/restart": {
"post": {
"description": "Restart listeners on all nodes.",
"parameters": [
{
"$ref": "#/components/parameters/listeners.listener_id"
}
],
"responses": {
"200": {
"description": "Updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST",
"BAD_LISTENER_ID"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listeners"
]
}
},
"/mqtt/retainer/message/{topic}": {
"delete": {
"description": "Delete matching messages.",
"parameters": [
{
"description": "Topic.",
"in": "path",
"name": "topic",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Unsupported backend.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Retainer"
]
},
"get": {
"description": "Lookup a message by a topic without wildcards.",
"parameters": [
{
"description": "Topic.",
"in": "path",
"name": "topic",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Details of the message.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/retainer.message"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Unsupported backend.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Viewed message doesn't exist.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Retainer"
]
}
},
"/rule_events": {
"get": {
"description": "List all events can be used in rules",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_rule_api_schema.rule_events"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "List Events",
"tags": [
"Rules"
]
}
},
"/clients/{clientid}/unsubscribe": {
"post": {
"description": "Unsubscribe",
"parameters": [
{
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_clients.unsubscribe"
}
}
}
},
"responses": {
"204": {
"description": "Unsubscribe OK"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENTID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Clients"
]
}
},
"/plugins/install": {
"post": {
"description": "Install a plugin(plugin-vsn.tar.gz).Follow [emqx-plugin-template](https://github.com/emqx/emqx-plugin-template) to develop plugin.",
"parameters": [],
"requestBody": {
"content": {
"multipart/form-data": {
"encoding": {
"plugin": {
"contentType": "application/gzip"
}
},
"schema": {
"properties": {
"plugin": {
"format": "binary",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UNEXPECTED_ERROR",
"ALREADY_INSTALLED",
"BAD_PLUGIN_INFO"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Plugins"
]
}
},
"/gateways/lwm2m/clients/{clientid}/read": {
"post": {
"description": "Send a read command to a resource",
"parameters": [
{
"example": "urn:oma:lwm2m:oma:2",
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
},
{
"example": "/3/0/7",
"in": "query",
"name": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENT_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "clientid not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Read Value from a Resource Path",
"tags": [
"LwM2M Gateways"
]
}
},
"/banned/{as}/{who}": {
"delete": {
"description": "Remove a client ID, username or IP address from the blacklist.",
"parameters": [
{
"description": "Ban method, which can be client ID, username or IP address.",
"example": "username",
"in": "path",
"name": "as",
"required": true,
"schema": {
"enum": [
"clientid",
"username",
"peerhost"
],
"type": "string"
}
},
{
"description": "Ban object, specific client ID, username or IP address.",
"example": "Badass",
"in": "path",
"name": "who",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Delete banned success"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "The banned object was not found in the blacklist.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Banned"
]
}
},
"/configs_reset/{rootname}": {
"post": {
"description": "Reset the config entry specified by the query string parameter `conf_path`.
- For a config entry that has default value, this resets it to the default value;
- For a config entry that has no default value, an error 400 will be returned",
"parameters": [
{
"example": "sysmon",
"in": "path",
"name": "rootname",
"required": true,
"schema": {
"enum": [
"zones",
"node",
"cluster",
"log",
"broker",
"sys_topics",
"sysmon",
"alarm",
"persistent_session_store",
"trace",
"dashboard",
"limiter"
],
"type": "string"
}
},
{
"description": "The config path separated by '.' character",
"example": "os.sysmem_high_watermark",
"in": "query",
"name": "conf_path",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Rest config successfully"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NO_DEFAULT_VALUE",
"REST_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"REST_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/mqtt/retainer": {
"get": {
"description": "View config",
"parameters": [],
"responses": {
"200": {
"description": "The config content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/retainer.retainer"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Config not found.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Retainer"
]
},
"put": {
"description": "Update retainer config.",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/retainer.retainer"
}
}
}
},
"responses": {
"200": {
"description": "Update configs successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/retainer.retainer"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Update config failed",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Retainer"
]
}
},
"/listeners/{listener_id}/authentication/{id}/status": {
"get": {
"description": "Get authenticator status from listener authentication chain.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"status_metrics": {
"summary": "Authn status metrics",
"value": {
"metrics": {
"failed": 0,
"nomatch": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"success": 0,
"total": 0
},
"node_error": [],
"node_metrics": [
{
"metrics": {
"failed": 0,
"matched": 0,
"nomatch": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"total": 0
},
"node": "emqx@127.0.0.1"
}
],
"node_resource_metrics": [
{
"metrics": {
"failed": 0,
"matched": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"success": 0
},
"node": "emqx@127.0.0.1"
}
],
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": "connected"
}
],
"resource_metrics": {
"failed": 0,
"matched": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"success": 0
},
"status": "connected"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_schema.metrics_status_fields"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
}
},
"/authorization/cache": {
"delete": {
"description": "Clean all authorization cache in the cluster.",
"parameters": [],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/listeners/{listener_id}/authentication": {
"get": {
"description": "List authenticators for listener authentication.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": [
{
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
},
{
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
},
{
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
},
{
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
},
{
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
],
"schema": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
},
"post": {
"description": "Create authenticator for listener authentication.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"jwt": {
"summary": "JWT authentication",
"value": {
"algorithm": "hmac-based",
"mechanism": "jwt",
"secret": "mysecret",
"secret_base64_encoded": false,
"use_jwks": false,
"verify_claims": {
"username": "${username}"
}
}
},
"password_based:built_in_database": {
"summary": "Built-in password_based authentication",
"value": {
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"user_id_type": "username"
}
},
"password_based:http": {
"summary": "password_based authentication through external HTTP API",
"value": {
"backend": "http",
"body": {
"password": "${password}",
"username": "${username}"
},
"connect_timeout": 5000,
"enable_pipelining": 100,
"headers": {
"content-type": "application/json"
},
"mechanism": "password_based",
"method": "post",
"pool_size": 8,
"request_timeout": 5000,
"ssl": {
"enable": false
},
"url": "http://127.0.0.1:18083"
}
},
"password_based:mongodb": {
"summary": "password_based authentication with MongoDB backend",
"value": {
"backend": "mongodb",
"collection": "users",
"database": "example",
"filter": {
"username": "${username}"
},
"is_superuser_field": "is_superuser",
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"password_hash_field": "password_hash",
"salt_field": "salt",
"server": "127.0.0.1:27017"
}
},
"password_based:redis": {
"summary": "password_based authentication with Redis backend",
"value": {
"backend": "redis",
"cmd": "HMGET ${username} password_hash salt",
"database": 0,
"mechanism": "password_based",
"password_hash_algorithm": {
"name": "sha256",
"salt_position": "suffix"
},
"redis_type": "single",
"server": "127.0.0.1:6379"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/authn-scram-builtin_db.authentication"
},
{
"$ref": "#/components/schemas/authn-jwt.jwks"
},
{
"$ref": "#/components/schemas/authn-jwt.public-key"
},
{
"$ref": "#/components/schemas/authn-jwt.hmac-based"
},
{
"$ref": "#/components/schemas/authn-http.post"
},
{
"$ref": "#/components/schemas/authn-http.get"
},
{
"$ref": "#/components/schemas/authn-redis.sentinel"
},
{
"$ref": "#/components/schemas/authn-redis.cluster"
},
{
"$ref": "#/components/schemas/authn-redis.standalone"
},
{
"$ref": "#/components/schemas/authn-mongodb.sharded-cluster"
},
{
"$ref": "#/components/schemas/authn-mongodb.replica-set"
},
{
"$ref": "#/components/schemas/authn-mongodb.standalone"
},
{
"$ref": "#/components/schemas/authn-postgresql.authentication"
},
{
"$ref": "#/components/schemas/authn-mysql.authentication"
},
{
"$ref": "#/components/schemas/authn-builtin_db.authentication"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"ALREADY_EXISTS"
],
"type": "string"
},
"message": {
"description": "ALREADY_EXISTS",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
}
},
"/api_key/{name}": {
"delete": {
"description": "Delete the specific api_key",
"parameters": [
{
"$ref": "#/components/parameters/api_key.name"
}
],
"responses": {
"204": {
"description": "Delete successfully"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"API Keys"
]
},
"get": {
"description": "Return the specific api_key",
"parameters": [
{
"$ref": "#/components/parameters/api_key.name"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"description": "Unique and format by [a-zA-Z0-9-_]",
"example": "EMQX-API-KEY-1",
"type": "string"
},
"api_key": {
"description": "TODO:uses HMAC-SHA256 for signing.",
"example": "a4697a5c75a769f6",
"type": "string"
},
"expired_at": {
"default": "infinity",
"description": "No longer valid datetime",
"example": "2021-12-05T02:01:34.186Z",
"oneOf": [
{
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"created_at": {
"description": "ApiKey create datetime",
"example": "2021-12-01T00:00:00.000Z",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"desc": {
"example": "Note",
"type": "string"
},
"enable": {
"description": "Enable/Disable",
"type": "boolean"
},
"expired": {
"description": "Expired",
"type": "boolean"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"API Keys"
]
},
"put": {
"description": "Update the specific api_key",
"parameters": [
{
"$ref": "#/components/parameters/api_key.name"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"expired_at": {
"default": "infinity",
"description": "No longer valid datetime",
"example": "2021-12-05T02:01:34.186Z",
"oneOf": [
{
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"desc": {
"example": "Note",
"type": "string"
},
"enable": {
"description": "Enable/Disable",
"type": "boolean"
},
"expired": {
"description": "Expired",
"type": "boolean"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"description": "Unique and format by [a-zA-Z0-9-_]",
"example": "EMQX-API-KEY-1",
"type": "string"
},
"api_key": {
"description": "TODO:uses HMAC-SHA256 for signing.",
"example": "a4697a5c75a769f6",
"type": "string"
},
"expired_at": {
"default": "infinity",
"description": "No longer valid datetime",
"example": "2021-12-05T02:01:34.186Z",
"oneOf": [
{
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
{
"enum": [
"infinity"
],
"type": "string"
}
]
},
"created_at": {
"description": "ApiKey create datetime",
"example": "2021-12-01T00:00:00.000Z",
"oneOf": [
{
"description": "epoch-second",
"example": 1640995200,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
},
"desc": {
"example": "Note",
"type": "string"
},
"enable": {
"description": "Enable/Disable",
"type": "boolean"
},
"expired": {
"description": "Expired",
"type": "boolean"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"API Keys"
]
}
},
"/clients/{clientid}/subscriptions": {
"get": {
"description": "Get client subscriptions",
"parameters": [
{
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_subscriptions.subscription"
},
"type": "array"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENTID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Clients"
]
}
},
"/configs": {
"get": {
"description": "Get all the configurations of the specified node, including hot and non-hot updatable items.",
"parameters": [
{
"description": "Node's name: If you do not fill in the fields, this node will be used by default.",
"example": "emqx@127.0.0.1",
"in": "query",
"name": "node",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"zones": {
"description": "A zone is a set of configs grouped by the zone name.
For flexible configuration mapping, the name can be set to a listener's zone config.
NOTE: A built-in zone named default is auto created and can not be deleted.
",
"properties": {
"$name": {
"$ref": "#/components/schemas/broker.zone"
}
},
"type": "object"
},
"node": {
"$ref": "#/components/schemas/emqx_conf_schema.node"
},
"cluster": {
"$ref": "#/components/schemas/emqx_conf_schema.cluster"
},
"log": {
"$ref": "#/components/schemas/emqx_conf_schema.log"
},
"broker": {
"description": "Message broker options.",
"$ref": "#/components/schemas/broker.broker"
},
"sys_topics": {
"description": "System topics configuration.",
"$ref": "#/components/schemas/broker.sys_topics"
},
"sysmon": {
"$ref": "#/components/schemas/broker.sysmon"
},
"alarm": {
"$ref": "#/components/schemas/broker.alarm"
},
"persistent_session_store": {
"$ref": "#/components/schemas/broker.persistent_session_store"
},
"trace": {
"$ref": "#/components/schemas/broker.trace"
},
"dashboard": {
"description": "Configuration for EMQX dashboard.",
"$ref": "#/components/schemas/dashboard.dashboard"
},
"limiter": {
"description": "Settings for the rate limiter.",
"$ref": "#/components/schemas/limiter.limiter"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_NODE"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/clients": {
"get": {
"description": "List clients",
"parameters": [
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
},
{
"description": "Node name",
"example": "emqx@127.0.0.1",
"in": "query",
"name": "node",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "User name",
"in": "query",
"name": "username",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "zone",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Client's IP address",
"example": "127.0.0.1",
"in": "query",
"name": "ip_address",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "The current connection status of the client, the possible values are connected,idle,disconnected",
"in": "query",
"name": "conn_state",
"required": false,
"schema": {
"enum": [
"connected",
"idle",
"disconnected"
],
"type": "string"
}
},
{
"description": "Whether the client uses a new session",
"in": "query",
"name": "clean_start",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"description": "Client protocol version",
"in": "query",
"name": "proto_ver",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Fuzzy search `clientid` as substring",
"in": "query",
"name": "like_clientid",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Fuzzy search `username` as substring",
"in": "query",
"name": "like_username",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Search client session creation time by greater than or equal method, rfc3339 or timestamp(millisecond)",
"in": "query",
"name": "gte_created_at",
"required": false,
"schema": {
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
}
},
{
"description": "Search client session creation time by less than or equal method, rfc3339 or timestamp(millisecond)",
"in": "query",
"name": "lte_created_at",
"required": false,
"schema": {
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
}
},
{
"description": "Search client connection creation time by greater than or equal method, rfc3339 or timestamp(epoch millisecond)",
"in": "query",
"name": "gte_connected_at",
"required": false,
"schema": {
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
}
},
{
"description": "Search client connection creation time by less than or equal method, rfc3339 or timestamp(millisecond)",
"in": "query",
"name": "lte_connected_at",
"required": false,
"schema": {
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/emqx_mgmt_api_clients.client"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/public.meta"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"INVALID_PARAMETER"
],
"type": "string"
},
"message": {
"description": "Invalid parameters",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Clients"
]
}
},
"/gateways/{name}/authentication/users": {
"get": {
"description": "Get the users for the authenticator (only supported by built_in_database).",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Page number of the results to fetch.",
"example": 1,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"minimum": 1,
"type": "integer"
}
},
{
"description": "Results per page(max 1000)",
"example": 50,
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"description": "Fuzzy search using user ID (username or clientid), only supports search by substring.",
"example": "test_",
"in": "query",
"name": "like_user_id",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Is superuser",
"in": "query",
"name": "is_superuser",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"data": [
{
"user_id": "user1"
},
{
"is_superuser": true,
"user_id": "user2"
}
],
"meta": {
"count": 300,
"limit": 20,
"page": 0
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_users"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "List users for a Gateway Authenticator",
"tags": [
"Gateway Authentication"
]
},
"post": {
"description": "Add user for the authenticator (only supports built_in_database).",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"regular_user": {
"summary": "Regular user",
"value": {
"password": "secret",
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"password": "secret",
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.request_user_create"
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"example": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Add User for a Gateway Authenticator",
"tags": [
"Gateway Authentication"
]
}
},
"/listeners/{id}": {
"delete": {
"description": "Delete the specified listener on all nodes.",
"parameters": [
{
"$ref": "#/components/parameters/listeners.listener_id"
}
],
"responses": {
"204": {
"description": "Listener deleted"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listeners"
]
},
"get": {
"description": "List all running node's listeners for the specified id.",
"parameters": [
{
"$ref": "#/components/parameters/listeners.listener_id"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "0.0.0.0:1884",
"current_connections": 10240,
"id": "tcp:demo",
"max_connections": 204800,
"mountpoint": "/",
"proxy_protocol": false,
"proxy_protocol_timeout": "3s",
"running": true,
"tcp_options": {
"active_n": 100,
"backlog": 1024,
"buffer": "4KB",
"high_watermark": "1MB",
"nodelay": false,
"reuseaddr": true,
"send_timeout": "15s",
"send_timeout_close": true
},
"type": "tcp",
"zone": "default"
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/listeners.quic_required_bind"
},
{
"$ref": "#/components/schemas/listeners.wss_required_bind"
},
{
"$ref": "#/components/schemas/listeners.ws_required_bind"
},
{
"$ref": "#/components/schemas/listeners.ssl_required_bind"
},
{
"$ref": "#/components/schemas/listeners.tcp_required_bind"
}
]
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_LISTENER_ID",
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Listener id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listeners"
]
},
"put": {
"description": "Update the specified listener on all nodes.",
"parameters": [
{
"$ref": "#/components/parameters/listeners.listener_id"
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "0.0.0.0:1884",
"current_connections": 10240,
"id": "tcp:demo",
"max_connections": 204800,
"mountpoint": "/",
"proxy_protocol": false,
"proxy_protocol_timeout": "3s",
"running": true,
"tcp_options": {
"active_n": 100,
"backlog": 1024,
"buffer": "4KB",
"high_watermark": "1MB",
"nodelay": false,
"reuseaddr": true,
"send_timeout": "15s",
"send_timeout_close": true
},
"type": "tcp",
"zone": "default"
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/listeners.quic_not_required_bind"
},
{
"$ref": "#/components/schemas/listeners.wss_not_required_bind"
},
{
"$ref": "#/components/schemas/listeners.ws_not_required_bind"
},
{
"$ref": "#/components/schemas/listeners.ssl_not_required_bind"
},
{
"$ref": "#/components/schemas/listeners.tcp_not_required_bind"
}
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"acceptors": 16,
"access_rules": [
"allow all"
],
"bind": "0.0.0.0:1884",
"current_connections": 10240,
"id": "tcp:demo",
"max_connections": 204800,
"mountpoint": "/",
"proxy_protocol": false,
"proxy_protocol_timeout": "3s",
"running": true,
"tcp_options": {
"active_n": 100,
"backlog": 1024,
"buffer": "4KB",
"high_watermark": "1MB",
"nodelay": false,
"reuseaddr": true,
"send_timeout": "15s",
"send_timeout_close": true
},
"type": "tcp",
"zone": "default"
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/listeners.quic_required_bind"
},
{
"$ref": "#/components/schemas/listeners.wss_required_bind"
},
{
"$ref": "#/components/schemas/listeners.ws_required_bind"
},
{
"$ref": "#/components/schemas/listeners.ssl_required_bind"
},
{
"$ref": "#/components/schemas/listeners.tcp_required_bind"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_LISTENER_ID",
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Listener id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listeners"
]
}
},
"/users/{username}/change_pwd": {
"post": {
"description": "Change dashboard user password",
"parameters": [
{
"description": "Dashboard Username",
"example": "admin",
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"old_pwd": {
"description": "Old password",
"type": "string"
},
"new_pwd": {
"description": "New password",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"204": {
"description": "Update user password successfully"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST",
"ERROR_PWD_NOT_MATCH"
],
"type": "string"
},
"message": {
"description": "Login failed. Bad username or password",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"USER_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Dashboard user not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Dashboard"
]
}
},
"/gateways/{name}/clients": {
"get": {
"description": "Get the gateway client list",
"parameters": [
{
"description": "Gateway Name",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Match the client's node name",
"example": "",
"in": "query",
"name": "node",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Match the client's ID",
"example": "",
"in": "query",
"name": "clientid",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Match the client's Username",
"example": "",
"in": "query",
"name": "username",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Match the client's ip address",
"example": "",
"in": "query",
"name": "ip_address",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Match the client's connection state",
"example": "",
"in": "query",
"name": "conn_state",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Match the client's protocol version",
"example": "",
"in": "query",
"name": "proto_ver",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Match the client's clean start flag",
"example": "",
"in": "query",
"name": "clean_start",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"description": "Use sub-string to match client's ID",
"example": "",
"in": "query",
"name": "like_clientid",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Use sub-string to match client's username",
"example": "",
"in": "query",
"name": "like_username",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Match the session created datetime greater than a certain value",
"example": "",
"in": "query",
"name": "gte_created_at",
"required": false,
"schema": {
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
}
},
{
"description": "Match the session created datetime less than a certain value",
"example": "",
"in": "query",
"name": "lte_created_at",
"required": false,
"schema": {
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
}
},
{
"description": "Match the client socket connected datetime greater than a certain value",
"example": "",
"in": "query",
"name": "gte_connected_at",
"required": false,
"schema": {
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
}
},
{
"description": "Match the client socket connected datatime less than a certain value",
"example": "",
"in": "query",
"name": "lte_connected_at",
"required": false,
"schema": {
"oneOf": [
{
"description": "epoch-millisecond",
"example": 1640995200000,
"type": "integer"
},
{
"example": "2022-01-01T00:00:00.000Z",
"format": "date-time",
"type": "string"
}
]
}
},
{
"description": "Match the lwm2m client's endpoint name",
"example": "",
"in": "query",
"name": "endpoint_name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Use sub-string to match lwm2m client's endpoint name",
"example": "",
"in": "query",
"name": "like_endpoint_name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Match the lwm2m client registered lifetime greater than a certain value",
"example": "",
"in": "query",
"name": "gte_lifetime",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Match the lwm2m client registered lifetime less than a certain value",
"example": "",
"in": "query",
"name": "lte_lifetime",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Page number of the results to fetch.",
"example": 1,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"minimum": 1,
"type": "integer"
}
},
{
"description": "Results per page(max 1000)",
"example": 50,
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"general_client_list": {
"summary": "General Client List",
"value": [
{
"send_pkt": 1,
"mailbox_len": 0,
"recv_cnt": 1,
"clean_start": true,
"connected": true,
"clientid": "MzAyMzEzNTUwNzk1NDA1MzYyMzIwNzUxNjQwMTY1NzQ0NjE",
"connected_at": "2021-12-07T10:44:02.721+08:00",
"subscriptions_max": "infinity",
"inflight_max": "infinity",
"awaiting_rel_max": "infinity",
"username": "guest",
"is_bridge": false,
"reductions": 72022,
"expiry_interval": 0,
"proto_name": "STOMP",
"subscriptions_cnt": 0,
"send_msg": 0,
"proto_ver": "1.0",
"mqueue_len": 0,
"inflight_cnt": 0,
"awaiting_rel_cnt": 0,
"disconnected_at": null,
"recv_oct": 56,
"send_oct": 61,
"mqueue_max": "infinity",
"keepalive": 0,
"ip_address": "127.0.0.1",
"recv_pkt": 1,
"node": "emqx@127.0.0.1",
"created_at": "2021-12-07T10:44:02.721+08:00",
"mqueue_dropped": 0,
"heap_size": 4185,
"recv_msg": 0,
"port": 50675,
"send_cnt": 1
}
]
},
"lwm2m_client_list": {
"summary": "LwM2M Client List",
"value": [
{
"send_pkt": 1,
"mailbox_len": 0,
"recv_cnt": 1,
"clean_start": true,
"connected": true,
"clientid": "MzAyMzEzNTUwNzk1NDA1MzYyMzIwNzUxNjQwMTY1NzQ0NjE",
"connected_at": "2021-12-07T10:44:02.721+08:00",
"subscriptions_max": "infinity",
"inflight_max": "infinity",
"awaiting_rel_max": "infinity",
"username": "guest",
"is_bridge": false,
"reductions": 72022,
"expiry_interval": 0,
"proto_name": "LwM2M",
"subscriptions_cnt": 0,
"send_msg": 0,
"proto_ver": "1.0",
"mqueue_len": 0,
"inflight_cnt": 0,
"awaiting_rel_cnt": 0,
"disconnected_at": null,
"recv_oct": 56,
"send_oct": 61,
"mqueue_max": "infinity",
"keepalive": 0,
"ip_address": "127.0.0.1",
"recv_pkt": 1,
"node": "emqx@127.0.0.1",
"created_at": "2021-12-07T10:44:02.721+08:00",
"endpoint_name": "urn:imei:154928475237123",
"mqueue_dropped": 0,
"heap_size": 4185,
"recv_msg": 0,
"port": 50675,
"send_cnt": 1,
"lifetime": 86400
}
]
}
},
"schema": {
"oneOf": [
{
"items": {
"$ref": "#/components/schemas/emqx_gateway_api_clients.exproto_client"
},
"type": "array"
},
{
"items": {
"$ref": "#/components/schemas/emqx_gateway_api_clients.lwm2m_client"
},
"type": "array"
},
{
"items": {
"$ref": "#/components/schemas/emqx_gateway_api_clients.coap_client"
},
"type": "array"
},
{
"items": {
"$ref": "#/components/schemas/emqx_gateway_api_clients.mqttsn_client"
},
"type": "array"
},
{
"items": {
"$ref": "#/components/schemas/emqx_gateway_api_clients.stomp_client"
},
"type": "array"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "List Gateway's Clients",
"tags": [
"Gateway Clients"
]
}
},
"/gateways/{name}/authentication/users/{uid}": {
"delete": {
"description": "Delete the user for the gateway authenticator (only supports built_in_database)",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID",
"example": "test_username",
"in": "path",
"name": "uid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "User Deleted"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Delete User for a Gateway Authenticator",
"tags": [
"Gateway Authentication"
]
},
"get": {
"description": "Get user info from the gateway authenticator (only supports built_in_database)",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID",
"example": "test_username",
"in": "path",
"name": "uid",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Get User Info for a Gateway Authenticator",
"tags": [
"Gateway Authentication"
]
},
"put": {
"description": "Update the user info for the gateway authenticator (only supports built_in_database)",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "User ID",
"example": "test_username",
"in": "path",
"name": "uid",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"regular_user": {
"summary": "Update regular user",
"value": {
"password": "newsecret"
}
},
"super_user": {
"summary": "Update user and promote to superuser",
"value": {
"is_superuser": true,
"password": "newsecret"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.request_user_update"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Update User Info for a Gateway Authenticator",
"tags": [
"Gateway Authentication"
]
}
},
"/gateways/{name}/listeners/{id}/authentication/import_users": {
"post": {
"description": "Import users into the gateway authenticator (only supports built_in_database)",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "stomp:tcp:def",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"properties": {
"filename": {
"format": "binary",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"204": {
"description": "Imported"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Import Users",
"tags": [
"Gateway Authentication"
]
}
},
"/rules/{id}/metrics/reset": {
"put": {
"description": "Reset a rule metrics",
"parameters": [
{
"example": "my_rule_id",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Reset Success"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Rule not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Reset a Rule Metrics",
"tags": [
"Rules"
]
}
},
"/gateways/{name}/listeners/{id}/authentication/users": {
"get": {
"description": "Get the users for the authenticator (only supported by built_in_database)",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Page number of the results to fetch.",
"example": 1,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"minimum": 1,
"type": "integer"
}
},
{
"description": "Results per page(max 1000)",
"example": 50,
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "List Authenticator's Users",
"tags": [
"Gateway Listeners"
]
},
"post": {
"description": "Add user for the authenticator (only supports built_in_database)",
"parameters": [
{
"description": "Gateway Name.
It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
",
"example": "stomp",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID",
"example": "",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"regular_user": {
"summary": "Regular user",
"value": {
"password": "secret",
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"password": "secret",
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.request_user_create"
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"example": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND",
"RESOURCE_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Add User for an Authenticator",
"tags": [
"Gateway Listeners"
]
}
},
"/authorization/settings": {
"get": {
"description": "Get authorization settings",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"required": [
"deny_action",
"no_match"
],
"properties": {
"no_match": {
"default": "allow",
"description": "
Default access control action if the user or client matches no ACL rules,
or if no such user or client is found by the configurable authorization
sources such as built_in_database, an HTTP API, or a query against PostgreSQL.
Find more details in 'authorization.sources' config.
",
"enum": [
"allow",
"deny"
],
"type": "string"
},
"deny_action": {
"default": "ignore",
"description": "The action when the authorization check rejects an operation.",
"enum": [
"ignore",
"disconnect"
],
"type": "string"
},
"cache": {
"$ref": "#/components/schemas/broker.authz_cache"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"put": {
"description": "Update authorization settings",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"deny_action",
"no_match"
],
"properties": {
"no_match": {
"default": "allow",
"description": "
Default access control action if the user or client matches no ACL rules,
or if no such user or client is found by the configurable authorization
sources such as built_in_database, an HTTP API, or a query against PostgreSQL.
Find more details in 'authorization.sources' config.
",
"enum": [
"allow",
"deny"
],
"type": "string"
},
"deny_action": {
"default": "ignore",
"description": "The action when the authorization check rejects an operation.",
"enum": [
"ignore",
"disconnect"
],
"type": "string"
},
"cache": {
"$ref": "#/components/schemas/broker.authz_cache"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"required": [
"deny_action",
"no_match"
],
"properties": {
"no_match": {
"default": "allow",
"description": "
Default access control action if the user or client matches no ACL rules,
or if no such user or client is found by the configurable authorization
sources such as built_in_database, an HTTP API, or a query against PostgreSQL.
Find more details in 'authorization.sources' config.
",
"enum": [
"allow",
"deny"
],
"type": "string"
},
"deny_action": {
"default": "ignore",
"description": "The action when the authorization check rejects an operation.",
"enum": [
"ignore",
"disconnect"
],
"type": "string"
},
"cache": {
"$ref": "#/components/schemas/broker.authz_cache"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/gateways/lwm2m/clients/{clientid}/write": {
"post": {
"description": "Send a write command to a resource",
"parameters": [
{
"example": "urn:oma:lwm2m:oma:2",
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
},
{
"example": "/3/0/7",
"in": "query",
"name": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"example": "Integer",
"in": "query",
"name": "type",
"required": true,
"schema": {
"enum": [
"Integer",
"Float",
"Time",
"String",
"Boolean",
"Opaque",
"Objlnk"
],
"type": "string"
}
},
{
"example": 123,
"in": "query",
"name": "value",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENT_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Clientid not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Write a Value to Resource Path",
"tags": [
"LwM2M Gateways"
]
}
},
"/configs/log": {
"get": {
"description": "Get the sub-configurations under *log*",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_conf_schema.log"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "config not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
},
"put": {
"description": "Update the sub-configurations under *log*",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_conf_schema.log"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_conf_schema.log"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"UPDATE_FAILED"
],
"type": "string"
},
"message": {
"description": "Error code to troubleshoot problems.",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Configs"
]
}
},
"/rules/{id}": {
"delete": {
"description": "Delete a rule by given Id from all nodes in the cluster",
"parameters": [
{
"example": "my_rule_id",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Delete rule successfully"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Delete a Rule",
"tags": [
"Rules"
]
},
"get": {
"description": "Get a rule by given Id",
"parameters": [
{
"example": "my_rule_id",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_rule_api_schema.rule_info"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Rule not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Get a Rule",
"tags": [
"Rules"
]
},
"put": {
"description": "Update a rule by given Id to all nodes in the cluster",
"parameters": [
{
"example": "my_rule_id",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_rule_api_schema.rule_creation"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_rule_api_schema.rule_info"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Invalid Parameters",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Update a Rule",
"tags": [
"Rules"
]
}
},
"/exhooks/{name}/hooks": {
"get": {
"description": "Get the hooks information of server",
"parameters": [
{
"description": "The Exhook server name",
"example": "default",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/exhook.list_hook_info"
},
"type": "array"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"ExHook"
]
}
},
"/bridges": {
"get": {
"description": "List all created bridges",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": [
{
"clean_start": true,
"egress": {
"local": {
"topic": "emqx/#"
},
"remote": {
"payload": "${payload}",
"qos": "${qos}",
"retain": false,
"topic": "from_emqx/${topic}"
}
},
"enable": true,
"ingress": {
"local": {
"payload": "${payload}",
"qos": "${qos}",
"retain": "${retain}",
"topic": "from_aws/${topic}"
},
"remote": {
"qos": 1,
"topic": "aws/#"
}
},
"keepalive": "300s",
"max_inflight": 100,
"metrics": {
"dropped": 0,
"dropped.expired": 0,
"dropped.other": 0,
"dropped.queue_full": 0,
"dropped.resource_not_found": 0,
"dropped.resource_stopped": 0,
"failed": 0,
"inflight": 0,
"late_reply": 0,
"matched": 0,
"queuing": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"received": 0,
"retried": 0,
"success": 0
},
"mode": "cluster_shareload",
"name": "mqtt_example",
"node_metrics": [
{
"metrics": {
"dropped": 0,
"dropped.expired": 0,
"dropped.other": 0,
"dropped.queue_full": 0,
"dropped.resource_not_found": 0,
"dropped.resource_stopped": 0,
"failed": 0,
"inflight": 0,
"late_reply": 0,
"matched": 0,
"queuing": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"received": 0,
"retried": 0,
"success": 0
},
"node": "emqx@127.0.0.1"
}
],
"password": "bar",
"proto_ver": "v4",
"resource_opts": {
"auto_restart_interval": "60s",
"health_check_interval": "15s",
"max_queue_bytes": 104857600,
"query_mode": "sync"
},
"retry_interval": "15s",
"server": "127.0.0.1:1883",
"ssl": {
"enable": false
},
"type": "mqtt",
"username": "foo"
},
{
"body": "${payload}",
"connect_timeout": "15s",
"enable": true,
"enable_pipelining": 100,
"local_topic": "emqx_webhook/#",
"max_retries": 3,
"method": "post",
"metrics": {
"dropped": 0,
"dropped.expired": 0,
"dropped.other": 0,
"dropped.queue_full": 0,
"dropped.resource_not_found": 0,
"dropped.resource_stopped": 0,
"failed": 0,
"inflight": 0,
"late_reply": 0,
"matched": 0,
"queuing": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"received": 0,
"retried": 0,
"success": 0
},
"name": "webhook_example",
"node_metrics": [
{
"metrics": {
"dropped": 0,
"dropped.expired": 0,
"dropped.other": 0,
"dropped.queue_full": 0,
"dropped.resource_not_found": 0,
"dropped.resource_stopped": 0,
"failed": 0,
"inflight": 0,
"late_reply": 0,
"matched": 0,
"queuing": 0,
"rate": 0,
"rate_last5m": 0,
"rate_max": 0,
"received": 0,
"retried": 0,
"success": 0
},
"node": "emqx@127.0.0.1"
}
],
"pool_size": 4,
"pool_type": "random",
"request_timeout": "15s",
"resource_opts": {
"async_inflight_window": 100,
"auto_restart_interval": 15000,
"health_check_interval": 15000,
"max_queue_bytes": 104857600,
"query_mode": "async",
"worker_pool_size": 1
},
"ssl": {
"enable": false
},
"type": "webhook",
"url": "http://localhost:9901/messages/${topic}"
}
],
"schema": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/bridge_mqtt.get"
},
{
"$ref": "#/components/schemas/bridge_webhook.get"
}
]
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "List Bridges",
"tags": [
"Bridges"
]
},
"post": {
"description": "Create a new bridge by type and name",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"examples": {
"mqtt_example": {
"summary": "MQTT Bridge",
"value": {
"clean_start": true,
"egress": {
"local": {
"topic": "emqx/#"
},
"remote": {
"payload": "${payload}",
"qos": "${qos}",
"retain": false,
"topic": "from_emqx/${topic}"
}
},
"enable": true,
"ingress": {
"local": {
"payload": "${payload}",
"qos": "${qos}",
"retain": "${retain}",
"topic": "from_aws/${topic}"
},
"remote": {
"qos": 1,
"topic": "aws/#"
}
},
"keepalive": "300s",
"max_inflight": 100,
"mode": "cluster_shareload",
"name": "mqtt_example",
"password": "bar",
"proto_ver": "v4",
"resource_opts": {
"auto_restart_interval": "60s",
"health_check_interval": "15s",
"max_queue_bytes": 104857600,
"query_mode": "sync"
},
"retry_interval": "15s",
"server": "127.0.0.1:1883",
"ssl": {
"enable": false
},
"type": "mqtt",
"username": "foo"
}
},
"webhook_example": {
"summary": "WebHook",
"value": {
"body": "${payload}",
"connect_timeout": "15s",
"enable": true,
"enable_pipelining": 100,
"local_topic": "emqx_webhook/#",
"max_retries": 3,
"method": "post",
"name": "webhook_example",
"pool_size": 4,
"pool_type": "random",
"request_timeout": "15s",
"resource_opts": {
"async_inflight_window": 100,
"auto_restart_interval": 15000,
"health_check_interval": 15000,
"max_queue_bytes": 104857600,
"query_mode": "async",
"worker_pool_size": 1
},
"ssl": {
"enable": false
},
"type": "webhook",
"url": "http://localhost:9901/messages/${topic}"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/bridge_mqtt.post"
},
{
"$ref": "#/components/schemas/bridge_webhook.post"
}
]
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"examples": {
"mqtt_example": {
"summary": "MQTT Bridge",
"value": {
"clean_start": true,
"egress": {
"local": {
"topic": "emqx/#"
},
"remote": {
"payload": "${payload}",
"qos": "${qos}",
"retain": false,
"topic": "from_emqx/${topic}"
}
},
"enable": true,
"ingress": {
"local": {
"payload": "${payload}",
"qos": "${qos}",
"retain": "${retain}",
"topic": "from_aws/${topic}"
},
"remote": {
"qos": 1,
"topic": "aws/#"
}
},
"keepalive": "300s",
"max_inflight": 100,
"mode": "cluster_shareload",
"name": "mqtt_example",
"password": "bar",
"proto_ver": "v4",
"resource_opts": {
"auto_restart_interval": "60s",
"health_check_interval": "15s",
"max_queue_bytes": 104857600,
"query_mode": "sync"
},
"retry_interval": "15s",
"server": "127.0.0.1:1883",
"ssl": {
"enable": false
},
"type": "mqtt",
"username": "foo"
}
},
"webhook_example": {
"summary": "WebHook",
"value": {
"body": "${payload}",
"connect_timeout": "15s",
"enable": true,
"enable_pipelining": 100,
"local_topic": "emqx_webhook/#",
"max_retries": 3,
"method": "post",
"name": "webhook_example",
"pool_size": 4,
"pool_type": "random",
"request_timeout": "15s",
"resource_opts": {
"async_inflight_window": 100,
"auto_restart_interval": 15000,
"health_check_interval": 15000,
"max_queue_bytes": 104857600,
"query_mode": "async",
"worker_pool_size": 1
},
"ssl": {
"enable": false
},
"type": "webhook",
"url": "http://localhost:9901/messages/${topic}"
}
}
},
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/bridge_mqtt.get"
},
{
"$ref": "#/components/schemas/bridge_webhook.get"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"ALREADY_EXISTS"
],
"type": "string"
},
"message": {
"description": "Bridge already exists",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"summary": "Create Bridge",
"tags": [
"Bridges"
]
}
},
"/listeners_status": {
"get": {
"description": "List all running node's listeners live status. group by listener type",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": [
{
"enable": false,
"ids": [
"tcp:demo"
],
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 11,
"max_connections": 1024000,
"running": true
}
},
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 10,
"max_connections": 1024000,
"running": true
}
}
],
"status": {
"current_connections": 21,
"max_connections": 2048000,
"running": true
},
"type": "tcp"
},
{
"enable": false,
"ids": [
"ssl:default"
],
"node_status": [
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 31,
"max_connections": "infinity",
"running": true
}
},
{
"node": "emqx@127.0.0.1",
"status": {
"current_connections": 40,
"max_connections": "infinity",
"running": true
}
}
],
"status": {
"current_connections": 71,
"max_connections": "infinity",
"running": true
},
"type": "ssl"
}
],
"schema": {
"items": {
"$ref": "#/components/schemas/listeners.listener_type_status"
},
"type": "array"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listeners"
]
}
},
"/monitor": {
"get": {
"description": "List monitor data.",
"parameters": [
{
"description": "The latest N seconds data. Like 300 for 5 min.",
"example": 300,
"in": "query",
"name": "latest",
"required": false,
"schema": {
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/emqx_dashboard_monitor_api.sampler"
},
"type": "array"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_RPC"
],
"type": "string"
},
"message": {
"description": "Bad RPC",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Metrics"
]
}
},
"/logout": {
"post": {
"description": "Dashboard user logout",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"username": {
"description": "Dashboard Username",
"example": "admin",
"maxLength": 100,
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"204": {
"description": "Dashboard logout successfully"
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_USERNAME_OR_PWD"
],
"type": "string"
},
"message": {
"description": "Login failed. Bad username or password",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Dashboard"
]
}
},
"/authorization/sources/built_in_database/rules/all": {
"delete": {
"description": "Delete rules for 'all'",
"parameters": [],
"responses": {
"204": {
"description": "Deleted"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"get": {
"description": "Show the list of rules for 'all'",
"parameters": [],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"examples": {
"password_based:built_in_database": {
"summary": "All",
"value": {
"rules": [
{
"action": "publish",
"permission": "allow",
"topic": "test/toopic/1"
},
{
"action": "subscribe",
"permission": "allow",
"topic": "test/toopic/2"
},
{
"action": "all",
"permission": "deny",
"topic": "eq test/#"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rules"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
},
"post": {
"description": "Create/Update the list of rules for 'all'.",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"examples": {
"password_based:built_in_database": {
"summary": "All",
"value": {
"rules": [
{
"action": "publish",
"permission": "allow",
"topic": "test/toopic/1"
},
{
"action": "subscribe",
"permission": "allow",
"topic": "test/toopic/2"
},
{
"action": "all",
"permission": "deny",
"topic": "eq test/#"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authz_api_mnesia.rules"
}
}
}
},
"responses": {
"204": {
"description": "Updated"
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad rule schema",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Authorization"
]
}
},
"/listeners/{listener_id}/authentication/{id}/users": {
"get": {
"description": "List users in authenticator in listener authentication chain.",
"parameters": [
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/public.page"
},
{
"$ref": "#/components/parameters/public.limit"
},
{
"description": "Is superuser",
"in": "query",
"name": "is_superuser",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"data": [
{
"user_id": "user1"
},
{
"is_superuser": true,
"user_id": "user2"
}
],
"meta": {
"count": 300,
"limit": 20,
"page": 0
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_users"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
},
"post": {
"description": "Create users for authenticator in listener authentication chain.",
"parameters": [
{
"description": "Authenticator ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Listener ID.",
"example": "tcp:default",
"in": "path",
"name": "listener_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"regular_user": {
"summary": "Regular user",
"value": {
"password": "secret",
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"password": "secret",
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.request_user_create"
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"examples": {
"regular_user": {
"summary": "Regular user",
"value": {
"user_id": "user1"
}
},
"super_user": {
"summary": "Superuser",
"value": {
"is_superuser": true,
"user_id": "user2"
}
}
},
"schema": {
"$ref": "#/components/schemas/emqx_authn_api.response_user"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"BAD_REQUEST"
],
"type": "string"
},
"message": {
"description": "Bad Request",
"type": "string"
}
},
"type": "object"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Not Found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Listener Authentication"
]
}
},
"/clients/{clientid}/keepalive": {
"put": {
"description": "Set the online client keepalive by seconds",
"parameters": [
{
"in": "path",
"name": "clientid",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_clients.keepalive"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emqx_mgmt_api_clients.client"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"enum": [
"CLIENTID_NOT_FOUND"
],
"type": "string"
},
"message": {
"description": "Client id not found",
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
],
"tags": [
"Clients"
]
}
}
},
"servers": [
{
"url": "/api/v5"
}
]
}