# Change the config

This guide applies a new config file to a fleet of gateways, one gateway at a time. Clients move to the other gateways and keep their sessions.

The gateway reads its config once, when it starts. A change takes effect only when the gateway restarts. SIGHUP does not reload the config. The gateway logs `config not reloaded` and continues with its old config.

Before you start, you need:

* Two or more gateways that share a sessions bucket. See [Deploy for high availability](/mq-gateway/0.4/how-to/deploy-for-high-availability.md).
* The new config file.
* The `nats` CLI, with a user in each account that the gateways serve.

## 1. Check the new file

Run `check` with the new file:

```
mq-gateway check --config gateway.new.yaml
```

`check` reads `nats.url` from the file only. It ignores `--nats.url` and `MQG_` variables. It cannot check a file with `nats.embed: true`.

Fix every failure before you continue. An account that fails its check at start serves no clients until the next restart.

## 2. Add new streams, buckets and permissions

Do this step only if the new file adds a binding or a bucket.

1. Generate the resources and the permissions from the new file:

   ```
   mq-gateway generate --config gateway.new.yaml --format nats-cli > provision.sh

   mq-gateway generate --config gateway.new.yaml --format nats-server > permissions.conf
   ```

2. Create the new streams and buckets. See [Provision the streams and buckets](/mq-gateway/0.4/how-to/provision-streams-and-buckets.md).

3. Copy the topics that you narrowed into the new `permissions.conf`. See [Configure listeners and auth](/mq-gateway/0.4/how-to/configure-listeners-and-auth.md).

4. Reload the NATS servers.

5. Run `check` again.

## 3. Restart the gateways one at a time

Put the new file in place on each host. Then do these steps for each gateway:

1. Start lame duck mode with a signal, or with an admin request:

   ```
   mq-gateway signal ldm --pid <pid>

   nats req '$MQG.admin.server.gw-1.ldm' ''
   ```

   Send the request from the admin account.

2. Wait for the gateway to exit with status 0.

3. Start the gateway with the new file and the same `--id`.

4. Wait until `/readyz` returns `200`.

5. Check that the gateway serves every account. Do these checks:

   * `/healthz` lists no account under `errors`.

   * The reply to `ping` includes the gateway id:

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

     Send it from the admin account. The reply lists each account the gateway serves.

6. Go to the next gateway.

In lame duck mode, the gateway closes its listeners immediately. After `ldm.grace-period` (default `10s`), it closes its client connections a few at a time over `ldm.duration` (default `2m`). Each client reconnects to another gateway and resumes its session. An MQTT 5 client gets the reason "Server shutting down".

`/readyz` returns `200` even when an account failed its start-up check. Use `/healthz` or `ping` to find such an account.

## While the restart runs

Gateways with the old file and gateways with the new file serve at the same time. A client gets the behavior of the gateway it connects to.

* **Accounts:** only gateways with the new file serve an added account. Only gateways with the old file serve a removed account.
* **Bindings:** if only one file binds a topic, the other gateways refuse a QoS 1 publish to it. Add a stream before the restart. Remove one after it.
* **Sessions bucket:** gateways on different buckets do not share sessions. If you rename the bucket, clients lose their persistent sessions.
* **`--id`:** keep each gateway id different from all others.

A gateway that runs alone has no other gateway to take its clients. Lame duck mode still closes the clients gradually, and they reconnect after the restart.

## Changes that need no restart

The gateway follows these changes in NATS while it runs:

| Change                                                            | What the gateway does                                                                                                                                    |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A user's permissions                                              | NATS applies them to the next action of the client. An existing QoS 1 subscription keeps its consumer. To stop it immediately, revoke the credential     |
| A revoked credential                                              | The gateway disconnects the client. An MQTT 5 client gets "Not authorized"                                                                               |
| A user moved to another account                                   | Clients of a `fixed` listener move at once. Kick a `passthrough` client to move it now. See [Operate a fleet](/mq-gateway/0.4/how-to/operate-a-fleet.md) |
| A rotated `creds` file, or TLS client certificate, key or CA file | The gateway reads the file again at its next NATS reconnect. This applies to gateway users and `fixed` listeners                                         |
| A NATS server restart                                             | NATS connections move to the other servers                                                                                                               |

## Check it works

After the last gateway restarts:

* `mq-gateway check --config gateway.new.yaml` exits 0.
* `ping` in each account gets one reply from each gateway.
* If you added a binding, a client subscribes at QoS 1 to one of its topics and gets QoS 1.
