Admin subjects

The gateway answers NATS requests on these subjects, with JSON in and out. It serves them in the admin account alone, for every account it serves. A client account has no admin subscriber. To give the gateway an admin account, see Set up the admin account. Without one, the gateway serves no admin request.

Each subject names a scope, then an operation:

Subject	Who replies
$MQG.admin.server.<id>.<op>	The gateway with that id
$MQG.admin.ping.<op>	Every gateway
$MQG.admin.account.<account>.<op>	Every gateway that serves clients in the account

<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 at start. Send info on the ping scope to find the ids. <account> is the account name that NATS reports, and in operator mode the account's public key.

Operation	Scopes	Request	Reply
info	all	Empty	{"id", "version", "since", "accounts": {"<account>": {"mqtt", "amqp"}}}
list	all	Empty, or {"account": "<account>"}	{"id", "clients": [{"cid", "account", "protocol", "client_id", "remote", "since", "nats_server"}], "count", "truncated"}
kick	server, account	{"cid": <cid>} or {"client_id": "<id>", "account": "<account>"}	{"id", "kicked": true, "cid"} or {"id", "kicked": false, "reason"}
rebalance	server	{"account": "<account>", "server": "<name or URL>", "max": <n>, "over": "<duration>"}	{"started": true, "server", "max", "over"} or {"started": false, "reason"}
ldm	server	Empty	{"started": true} or {"started": false, "reason"}

For example:

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

Things to know

• Replies. On the ping and account scopes, each gateway sends its own reply with its id. Collect them until a timeout, as --replies 0 does.
• info. accounts holds the client counts of each account in scope. On the account scope, it holds that account alone.
• kick. A client ID is unique only within its account, so a kick by client ID names the account. The account scope names it already. A cid is unique on one gateway only, so the account scope refuses a kick by cid. 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 the reply leaves out clients.
• rebalance. Use it after a rolling restart leaves a NATS server with no client connections. It moves the clients of one account on one gateway. 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 ends. See Change the config.
• Not served. NATS can refuse the admin user or one of its subscriptions, or the admin connection can be down. The gateway then logs a warning and keeps serving clients. /healthz names the admin account.
• Without a routing table. The gateway asks each client's NATS user which account it is in. When the user cannot publish $SYS.REQ.USER.INFO, list shows the client with an empty account, and only the server and ping scopes reach it.
• Liveness. Gateways that share a sessions bucket ask each other $MQG.alive.<id> in that bucket's account, not in the admin account. A gateway whose admin connection is down still answers.

NATS permissions

• The gateway's admin user subscribes to the three scopes, publishes $SYS.REQ.USER.INFO, receives its replies and sends replies.
• An operator publishes to $MQG.admin.> and subscribes to its inbox.
• With a sessions bucket, the gateway user in each client account publishes and subscribes to $MQG.alive.* and sends replies.
• For rebalance with MQTT bindings, the gateway user in each client account publishes to $JS.API.CONSUMER.PAUSE.<stream>.* and $JS.API.CONSUMER.INFO.<stream>.*.
• Deny $MQG.> 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.