# 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](/mq-gateway/0.2/how-to/central-admin-account.md).

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