# 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](/mq-gateway/0.4/how-to/set-up-the-admin-account.md). 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](/mq-gateway/0.4/reference/cli.md#signals). 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](/mq-gateway/0.4/how-to/change-the-config.md).
* **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`](/mq-gateway/0.4/reference/cli.md#health-endpoint) 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`](/mq-gateway/0.4/reference/cli.md#generate) prints these permissions.
