> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# Back up, move, or restore pgw

> Back up pgw's data folder and master key, move pgw to another host, and restore it after the host is lost.

pgw has no cluster and no external database, so a backup is a copy of the data folder and of the master key that decrypts what is in it. Without the key, pgw can't read the push credentials and managed mode passwords in the data folder, and without the data folder, the key restores nothing. With both, you can rebuild pgw on any host under the same hostname, and no app or PBX needs a change.

> [!WARNING]
>
> Never run two pgw instances on the same data. Both would renew the same registrations and push to the same devices. On one host, pgw locks `data_dir`, and a second process exits with `data_dir is in use by another pgw process`. pgw can't lock a copy on another host.

## What to back up

The first two rows are essential. You can re-create the others.

| Item | Where | Needed for |
| - | - | - |
| `data_dir` | `/var/lib/pgw` | Tenants, apps, upstreams, users, and devices, in `pgw.db`. While pgw runs, `pgw.db-wal` and `pgw.db-shm` hold recent changes, and the three files belong together. |
| Master key | The file that `PGW_MASTER_KEY_FILE` names, or `.env` when you set pgw up with `pgw init` | Push credentials and managed mode passwords. Without the key, pgw can't read them. |
| Configuration | `/etc/pgw/config.yaml` | Settings, such as `hostname` and the listeners. |
| TLS certificate and key | `tls_cert_file`, `tls_key_file` | The app listener. You can also get a new certificate for the same name. |
| Bootstrap token | `/etc/pgw/bootstrap.env` | `pgw cert reload` and the `pgw ban` commands. The systemd unit doesn't start without the file. You can also create a new token. |

## Back up the data folder

Copy `data_dir` while pgw is stopped, so that the database files match each other. The stop lasts a few seconds, and apps connect again when they next register or wake. Copy to a folder that doesn't exist yet, because `cp` copies into an existing folder instead of replacing it:

```bash theme={null}
sudo systemctl stop pgw
sudo cp -a /var/lib/pgw /var/backups/pgw-data
sudo systemctl start pgw
sudo ls -1 /var/backups/pgw-data
```

The copy holds one database file. After a clean stop, pgw has merged its recent changes into `pgw.db`, so no `-wal` or `-shm` file remains:

```text theme={null}
pgw.db
pgw.lock
selfsigned.crt
selfsigned.key
```

To back up while pgw runs, take a filesystem snapshot that captures all three database files at the same moment.

## Move pgw to another host

These steps keep pgw's hostname, so no app and no PBX needs a change. The devices move with the data folder, so the new host can wake them at once. Before the move, lower the TTL of the hostname's DNS record, so that the change in step 6 takes effect quickly.

**1. Install pgw on the new host**

Follow [Install pgw on a server](https://docs.pgw.sipmicro.services/deploy/install.md) up to the configuration file. Don't start pgw.

**2. Copy the secrets and configuration**

Copy the master key, `config.yaml`, and `bootstrap.env` to the new host, and keep the key file and `bootstrap.env` at mode `600`. If you set pgw up with `pgw init`, copy `.env`, `config.yaml`, and `tenant.yaml` instead, and keep `.env` at mode `600`.

**3. Stop pgw on the old host**

```bash theme={null}
sudo systemctl stop pgw
sudo systemctl disable pgw
```

**4. Copy the data folder**

```bash theme={null}
sudo rsync -a /var/lib/pgw/ new-host:/var/lib/pgw/
```

On the new host, make the `pgw` user its owner.

```bash theme={null}
sudo chown -R pgw:pgw /var/lib/pgw
```

**5. Install the TLS certificate**

Copy the files that `tls_cert_file` and `tls_key_file` name from the old host to the same paths, and keep their owner, group, and mode, so that the `pgw` user can read them. pgw then starts with the certificate that apps already trust. After DNS points at the new host, set up renewal there as in [Install a TLS certificate](https://docs.pgw.sipmicro.services/deploy/tls.md).

**6. Point DNS at the new host**

Point the hostname's DNS record at the new host. If a PBX reaches pgw by IP address through `upstream_hostname`, change that setting too. If the PBX's own address changes, update the upstream's `invite_source_cidrs`.

**7. Start pgw on the new host**

```bash theme={null}
sudo systemctl enable --now pgw
```

After the start:

* Apps connect to the new host when they next register or wake. A call that arrives first still gets a call push, because the copied data holds the device.
* In managed mode, pgw renews every device's registration at the PBX from the new host, at `managed_renewals_per_second`.
* PBXs reach the new host once DNS changes.

## Restore pgw after the host is lost

| You have | Do this |
| - | - |
| A copy of `data_dir` and the master key | Follow the move steps, and skip stopping the old host. Use only a copy taken while pgw was stopped, or a snapshot of all three database files from the same moment. |
| The master key, but no database | Start pgw with an empty `data_dir`, and create the tenant, apps, upstreams, and users again. Devices get no calls until their apps register again. |
| No master key | Start with a new key and an empty `data_dir`, and set everything up again. |

## Check that it works

1. Run `pgw binding list`. Devices appear as their apps register.
2. Check `pgw_upstream_up` in `/metrics` for each upstream with a keepalive. The value is `1` when the PBX answers.
3. Call a device whose app is closed. It rings after a push.

## Next steps

> [card] [Upgrade pgw](https://docs.pgw.sipmicro.services/upgrade.md)
>
> Copy the data folder the same way before each upgrade, so that you can roll back.

> [card] [Database](https://docs.pgw.sipmicro.services/reference/database.md)
>
> Look up what each table in `pgw.db` holds before you inspect a backup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.