Skip to main content
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.
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.

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

4

Copy the data folder

On the new host, make the pgw user its owner.
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.
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

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

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

Upgrade pgw

Copy the data folder the same way before each upgrade, so that you can roll back.

Database

Look up what each table in pgw.db holds before you inspect a backup.