Admin subjects

The gateway answers NATS requests on these subjects, with JSON in and out. Each account's subjects act only on that account's MQTT and AMQP clients. To use them from one operator account, see Administer every account from one.

<id> is the gateway id, from id in the config file or --id. Without one, the gateway picks 16 random hex characters and logs them in the admin control enabled line. Send ping to find the ids.

Subject	What it does	Reply
$MQGW.admin.ping	Finds every gateway that serves the account. Send an empty request	One reply from each gateway: {"id", "version", "since", "clients": {"mqtt", "amqp"}}
$MQGW.admin.<id>.list	Lists the account's clients on this gateway. Send an empty request	{"clients": [{"cid", "protocol", "client_id", "remote", "since", "nats_server"}], "count", "truncated"}
$MQGW.admin.<id>.kick	Disconnects one client. Send {"cid": <cid>} or {"client_id": "<id>"}	{"kicked": true, "cid"} or {"kicked": false, "reason"}
$MQGW.admin.<id>.rebalance	Moves the account's client NATS connections onto one NATS server. Send {"server": "<name or URL>", "max": <n>, "over": "<duration>"}	{"started": true, "server", "max", "over"} or {"started": false, "reason"}
$MQGW.admin.<id>.ldm	Puts the gateway in lame duck mode. Only the gateway's own account has it	{"started": true} or {"started": false, "reason"}
$MQGW.admin.<id>.alive	Lets other gateways check that this gateway is alive. Only with a sessions bucket	Empty

For example:

nats req '$MQGW.admin.ping' '' --replies 0 --timeout 1s
nats req '$MQGW.admin.<id>.kick' '{"client_id": "sensor-7"}'
nats req '$MQGW.admin.<id>.rebalance' '{"server": "nats-3", "over": "30s"}'

Things to know

• kick. An MQTT v5 client gets DISCONNECT 0x98 Administrative action, and the gateway closes an MQTT 3.1.1 client. An AMQP client gets amqp:connection:forced. The gateway publishes the will of an MQTT client. If several connections have the client ID, kick one of them by cid from list.
• list. The reply holds at most 10,000 clients, and no more than fit in one NATS message. truncated is true when clients were left out.
• rebalance. Use it after a rolling restart leaves a NATS server with no client connections. Clients stay connected to the gateway. The gateway holds each client for a moment while its NATS connection moves. max and over are optional. If the first connection does not land on the server, the gateway stops the rebalance.
• ldm. It has the same effect as SIGUSR2. The gateway closes its listeners, and then closes its client connections over ldm.duration. It stops when lame duck mode is done. See Change the config.
• Not served. If NATS refuses the gateway user, or the user cannot subscribe to a subject, the gateway logs a warning and keeps serving clients. /healthz names the account.

NATS permissions

• In each account, the gateway user must be able to subscribe to the subjects and send replies.
• With a sessions bucket, the gateway user must also publish to $MQGW.admin.*.alive.
• For rebalance with MQTT bindings, the gateway user must also publish to $JS.API.CONSUMER.PAUSE.<stream>.* and $JS.API.CONSUMER.INFO.<stream>.*.
• An operator publishes to $MQGW.admin.> and subscribes to its inbox.
• Deny $MQGW.admin.> to client NATS users. The gateway refuses MQTT and AMQP clients on these subjects, but it does not check NATS clients.

mq-gateway generate --format nats-server prints these permissions.