# Operate a fleet

This guide lists the clients a gateway serves, removes one client, spreads NATS connections again after a NATS restart, and cuts off a fleet. A fleet is a NATS account. The [admin subjects](/mq-gateway/0.2/reference/admin-subjects.md) reference has each request and reply.

Before you start, you need:

* The `nats` CLI, with a user in the fleet's account.
* Permission for that user to publish on `$MQGW.admin.>` and to receive the replies. `generate --format nats-server` prints these as `$operator_permissions`.

## 1. Find the gateway IDs

Each admin subject holds a gateway id. Set it with `--id`. Without `--id`, the gateway picks one and logs it at start in the `admin control enabled` line.

To find every gateway that serves your account, send `ping`:

```
nats req '$MQGW.admin.ping' '' --replies 0 --timeout 1s
```

Each gateway replies with its id, version, start time and client counts.

## 2. List the clients

```
nats req '$MQGW.admin.fleet-a.list' ''
```

The reply lists the clients of your account on that gateway. Each has its connection id (`cid`), protocol, client ID, address, connect time and NATS server:

```
{"clients":[{"cid":3,"protocol":"mqtt","client_id":"sensor-41","remote":"10.0.4.17:51122","since":"2026-10-08T09:12:44Z","nats_server":"n1"}],"count":1,"truncated":false}
```

With several gateways, send `list` to each gateway id.

## 3. Remove one client

```
nats req '$MQGW.admin.fleet-a.kick' '{"client_id": "sensor-41"}'
```

The reply `{"kicked":true,"cid":3}` means that the disconnect started.

* An MQTT 5 client gets "Administrative action".
* An AMQP client gets `amqp:connection:forced`.
* The gateway publishes the client's will.

The client can reconnect. To keep it out, revoke its credential.

If a client ID matches more than one connection, the gateway refuses the kick. This can happen with AMQP container IDs. Kick by `cid` instead:

```
nats req '$MQGW.admin.fleet-a.kick' '{"cid": 7}'
```

## Rebalance after a NATS restart

When you restart NATS servers one at a time, client NATS connections move to the other servers. The last server you restart gets none of them back. To count the connections on each server:

```
nats req '$MQGW.admin.fleet-a.list' '' | jq -r '.clients[].nats_server' | sort | uniq -c
```

To move connections to the empty server, here `n3`:

```
nats req '$MQGW.admin.fleet-a.rebalance' '{"server": "n3", "over": "2m"}'
```

The gateway moves enough connections to give `n3` an equal share. To set a different number, add `max`. `over` spreads the moves over time. Clients stay connected while their NATS connections move. The gateway logs `rebalance finished` at the end.

If `n3` is down or in lame duck mode, the gateway refuses the request and gives the reason.

Send `rebalance` to each gateway, in each account. Each request moves only the clients of one account on one gateway.

## Revoke a user or a fleet

Remove the user from the NATS server config, or revoke its JWT. Then reload the server:

```
nats-server --signal reload
```

In operator mode, use `nsc revocations add-user` and push the account.

NATS closes every connection of the user. The gateway then disconnects those clients within a few seconds:

* An MQTT 5 client gets "Not authorized".
* The gateway publishes each will.
* A revoked client that reconnects gets "Not authorized".

Other fleets are not affected, because their clients act as other users.

## Stop serving a fleet

Remove the account's credential from `accounts` in the config file. Then restart the gateways, as in [Change the config](/mq-gateway/0.2/how-to/change-the-config.md).

## Check it works

* After a kick, `list` no longer shows the `cid`.
* After a rebalance, the `jq` count shows connections on `n3`.
* After a revoke, the revoked clients are no longer in `list`.
