Skip to main content

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 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.

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.