EMQX MQTT broker

v0.1.0

Operate an EMQX 5 or 6 MQTT broker over its REST API: node, listener, throughput, and alarm status; client sessions, subscriptions, topic routes, and retained messages; authentication, authorization, and rule engine counters; and client kicks and bans, rule and action toggles, connector reconnects, listener restarts, and retained message deletes. The API key and secret are streamed over curl stdin.

16 allowed by default 9 need approval by default

Pack ID

emqx

Vendor

emisar

linux

Actions

Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.


              curl

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host

sudo emisar pack install emqx --hash sha256:793c6e7eb219bae412cbea9e4065dfe909791fa2036933e7603f89c1d7675780

Setup

Every action calls the EMQX REST API at $EMQX_URL via curl on the runner host, with HTTP Basic auth from $EMQX_API_KEY and $EMQX_API_SECRET sent over curl stdin, so neither appears in the process arguments or the audit log.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

EMQX_URL default http://127.0.0.1:18083

Base URL of the dashboard listener, which serves the REST API — scheme, host, and port. Each action appends its /api/v5 path.
EMQX_API_KEY required

An API key from the Dashboard's System → API Key page, or the first field of an api_key.bootstrap_file line ( <key>:<secret>:<role> ). The viewer role runs every read. The actions that change the broker (kick, ban, unban, rule and action toggles, connector start, listener restart, retained message delete) need administrator . Roles exist in EMQX 5.9 and later and in Enterprise 5.3 and later; open-source 5.8 keys are always administrators.
EMQX_API_SECRET required

The key's secret, shown once when the key is created, or the second field of the bootstrap file line.

Notes

Any of EMQX_URL / EMQX_API_KEY / EMQX_API_SECRET you set must also be allowlisted in the runner's execution.inherit_env — the action env is scrubbed to PATH/LANG/LC_ALL/TERM by default, so an env present on the host but not allowlisted is silently dropped (the action falls back to its local default or fails auth).
Each write is one request against one named client, ban, rule, action, connector, listener, or topic. Publishing, creating or editing rules, connectors, and actions, built-in database users and ACL rules, cluster membership, configuration, plugins, gateways, and message tracing are not included.
Connector, action, and authenticator configurations are not read: EMQX masks password and authorization header values in them but not custom headers such as API keys. Their status and counters come from emqx.rule_metrics, emqx.auth_metrics, and emqx.alarms.

Verify it works

Runs emqx.nodes, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host

sudo emisar pack verify emqx

Install and configure a pack walks through the whole sequence on a host.

Actions 25 total

View on GitHub

emqx.alarms script low

List EMQX alarms

List the alarms raised now, or the history of cleared ones, with GET /api/v5/alarms: each alarm's name, node, message, details, and when it was raised and cleared. A connector or action that went down raises one naming it and the reason, such as "resource down: Connection refused". At most 100 alarms per call.
View source on GitHub
emqx.auth_metrics script low

Show authentication and authorization outcomes

Show each authenticator's and authorization source's enabled and up status, success, failure, and no-match counts per authenticator, allow and deny counts and rule count per source, and the ban count, summed across the cluster, as Prometheus text from GET /api/v5/prometheus/auth. Runner redaction masks the backend in password-based authenticator IDs, so they read password_based:[REDACTED]; every counter stays readable.
View source on GitHub
emqx.authz_settings script low

Show authorization settings

Show what EMQX does when no authorization rule matches a publish or subscribe (no_match), what it does on a deny (deny_action: ignore or disconnect), and the authorization cache settings, with GET /api/v5/authorization/settings. Allow and deny counts per source are in emqx.auth_metrics.
View source on GitHub
emqx.ban script high

Ban an MQTT client, user, or address

Add a ban with POST /api/v5/banned: EMQX disconnects every matching live client and refuses its connections until the ban ends or emqx.unban lifts it. A peerhost ban shuts out every device behind that address, such as a whole site behind one NAT. Returns the stored ban.
View source on GitHub
emqx.banned script low

List banned MQTT clients

List the ban table with GET /api/v5/banned: each ban's kind (client ID, username, or peer host), value, reason, who created it, and when it started and ends.
View source on GitHub
emqx.client script low

Show one MQTT client

Show one client's session with GET /api/v5/clients/{clientid}: whether it is connected, when it connected, its address, listener, protocol, and keepalive, clean start and session expiry, subscription, inflight, and queue counts and limits, and its message, packet, and byte counters. Fails with CLIENTID_NOT_FOUND when the broker holds no session for that ID. Credentials and message contents are not returned.
View source on GitHub
emqx.clients script low

Find MQTT clients

List client sessions, connected or not, with GET /api/v5/clients, filtered by client ID or username substring, exact IP address, and connection state: each client's ID, username, address, node, protocol version, keepalive, connect time, subscription count, inflight and queued message counts, and messages received and sent. meta.hasnext says whether more sessions matched than limit. Credentials and message contents are not returned.
View source on GitHub
emqx.delete_retained script high

Delete a retained message

Delete the retained message on one exact topic with DELETE /api/v5/mqtt/retainer/message/{topic}, so new subscribers stop receiving it. It cannot be restored; only its publisher can retain a new one. Fails with NOT_FOUND when the topic holds no retained message; emqx.retained lists them.
View source on GitHub
emqx.kick_client script high

Disconnect an MQTT client

Disconnect one client and discard its session with DELETE /api/v5/clients/{clientid}. A client with reconnect logic comes back with a new session; subscriptions and queued messages it does not restore are lost. Fails with CLIENTID_NOT_FOUND when no session exists. emqx.ban keeps a client out.
View source on GitHub
emqx.listeners script low

List EMQX listeners

List MQTT listeners with their bind address, running state, and current and maximum connections per node with GET /api/v5/listeners. Status only; TLS settings are not returned.
View source on GitHub
emqx.metrics script low

Show EMQX message and packet counters

Show the counters EMQX keeps since each node started, summed across the cluster, with GET /api/v5/metrics: messages received, sent, delivered, and dropped by reason, packets by type, client connects, disconnects, and auth results, and session events.
View source on GitHub
emqx.nodes script low

Show EMQX cluster nodes

Show each EMQX node's status, version, edition, role, uptime, connection count, memory, and process use with GET /api/v5/nodes.
View source on GitHub
emqx.rates script low

Show current EMQX throughput

Show the cluster's current connection, live connection, topic, subscription, and retained message counts, and its per-second received, sent, and dropped message rates, with GET /api/v5/monitor_current. These are the numbers on the Dashboard overview.
View source on GitHub
emqx.restart_listener script high

Restart an MQTT listener

Restart one listener's acceptor on every node with POST /api/v5/listeners/{type:name}/restart, which also starts a listener that stopped. New connections to it are refused until it is back; clients already connected stay connected. emqx.listeners lists listener IDs such as tcp:default and whether each is running.
View source on GitHub
emqx.retained script low

List retained messages

List retained messages with GET /api/v5/mqtt/retainer/messages, optionally only those on topics that match a filter such as devices/+/config: each message's topic, QoS, publisher client ID and username, and publish time. Payloads are not returned; emqx.retained_message reads one.
View source on GitHub
emqx.retained_message script high

Read a retained message

Read one retained message, payload included, with GET /api/v5/mqtt/retainer/message/{topic}. The payload is the publisher's raw message body, base64-encoded, and can hold device data, commands, or credentials, which is why this read is high risk. Fails with NOT_FOUND when the topic holds no retained message; emqx.retained lists them without payloads.
View source on GitHub
emqx.rule_metrics script low

Show rule engine metrics

Show matched, passed, and failed counts per rule, each action's enabled and up status with its success, failure, drop, retry, and queue counts, and each connector's enabled and up status, summed across the cluster, as Prometheus text from GET /api/v5/prometheus/data_integration. Rules, actions, and connectors appear by ID; emqx.rules shows rule SQL.
View source on GitHub
emqx.rules script low

List rule engine rules

List rule engine rules with GET /api/v5/rules: each rule's ID, name, description, whether it is enabled, the topics it reads, its SQL, the actions it sends results to, and when it was created and last changed. Per-rule counters are in emqx.rule_metrics.
View source on GitHub
emqx.set_data_action_enabled script high

Enable or disable a data integration action

Enable or disable one action, the sink rules send results to, with PUT /api/v5/actions/{type:name}/enable/{true|false}. While it is disabled its rules' results are not delivered to it, and they are not replayed when it is enabled again.
View source on GitHub
emqx.set_rule_enabled script high

Enable or disable a rule

Enable or disable one rule engine rule with PUT /api/v5/rules/{id}, and return the updated rule. A disabled rule stops matching messages, so its actions receive nothing until it is enabled again, and messages published meanwhile are not replayed. The rule's SQL and actions stay as they are.
View source on GitHub
emqx.start_connector script high

Start a data integration connector

Start or reconnect one connector on every node with POST /api/v5/connectors/{type:name}/start, as after the database, HTTP service, or Kafka cluster it connects to comes back. Fails with the connection error while that system is still unreachable.
View source on GitHub
emqx.stats script low

Show connection, subscription, and retained-message counts

Show cluster-wide current counts and peaks for connections, sessions, subscriptions, topics, and retained messages with GET /api/v5/stats?aggregate=true.
View source on GitHub
emqx.subscriptions script low

List MQTT subscriptions

List subscriptions with GET /api/v5/subscriptions, for one client ID or for topic filters that fall under a filter such as plant/#: each subscription's client, topic filter, QoS, node, and its no local, retain as published, and retain handling options.
View source on GitHub
emqx.topics script low

List MQTT topic routes

List the topic filters at least one client subscribes to, with the node that routes each one, with GET /api/v5/topics, or check one exact topic filter. An empty result for a filter means no client is subscribed to it anywhere in the cluster.
View source on GitHub
emqx.unban script high

Lift a ban

Remove one ban with DELETE /api/v5/banned/{kind}/{who}, so that client, user, or address can connect again. Fails with NOT_FOUND when no such ban exists; emqx.banned lists them.
View source on GitHub

← Back to registry

Pack reference Publish your own