# 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.2/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 `MQGW_` 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.2/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.2/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 from the gateway's own account:

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

   nats req '$MQGW.admin.gw-1.ldm' ''
   ```

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

   * In each account, the reply to `ping` includes the gateway id:

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

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