Skip to main content
To upgrade, you replace the binary and restart pgw. pgw updates its database by itself when a new release first starts. An earlier release can still read the updated database, so you can roll back without restoring anything.

Before you begin

Read the release notes for each release since yours, and act on the entries marked Breaking. If you use managed mode and the running release is 0.3.1 or earlier, also do Keep per-device registration during the upgrade before you start pgw again.

Upgrade pgw

pgw is down between the stop and the start, so calls that arrive in that time fail. Apps connect again when they next register or wake.
1

Stop pgw and copy the data folder

The copy is your way back if the database is ever damaged. Copy data_dir to a folder that doesn’t exist yet, because cp copies into an existing folder instead of replacing it:
2

Replace the binary and start pgw

Install the new release over /usr/local/bin/pgw, as in Install pgw on a server. Then start pgw:

Check that it works

pgw version shows the new release, and the list shows the devices that were registered before the upgrade.

Upgrade managed mode from 0.3.1 or earlier

Releases up to 0.3.1 register one contact for each device at the PBX. Later releases register one contact for each user by default. If the default changed under a running install, the PBX would hold both kinds of contact at once and could refuse the new one. So you keep the old behavior during the upgrade, and switch afterward, one upstream at a time.

Keep per-device registration during the upgrade

Before you start the new release, add this line to the [Service] section of /etc/systemd/system/pgw.service, and reload systemd:
Without it, pgw registers one contact per user at its first start, while the PBX still holds one contact per device. A PBX that refuses contacts over its limit refuses the user’s contact. After five refusals in a row, pgw removes the user’s devices, and they get no calls until the old contacts expire at the PBX and the apps register again. Set the variable in the environment, not in config.yaml, so that a rollback doesn’t need to remove it.
While a managed upstream uses the gateway default, don’t restart pgw with a different value of managed_registration or PGW_MANAGED_REGISTRATION. To change how an upstream registers, run pgw upstream update on the running gateway.

Switch to per-user registration

Switch after pgw has run for at least the upstream’s max_expires, 3600 seconds by default. By then, the running pgw has itself registered every device contact that the PBX holds, so it can remove each one.
1

Leave room at the PBX

During the switch, the PBX holds the user’s device contacts and the user’s new contact at once. Give each account room for at least max_bindings_per_aor plus 1 contacts, plus one for each other phone on the account. For the setting, see the page for your PBX: Asterisk or FreeSWITCH.Without the room, the PBX refuses the user’s contact, and the user can lose calls. See Choose how pgw registers devices.
2

Switch each managed upstream

3

Check the log

pgw logs registration of the previous mode removed at the upstream, with the user’s aor, for each device contact that it removes. The switch is done when the log has this line for every device of every user.
The upstream’s own setting now overrides PGW_MANAGED_REGISTRATION. Remove the variable only after every managed upstream has its own setting.

Roll back an upgrade

To roll back, run the earlier release on the same data_dir. It keeps what the new release stored, and ignores what it doesn’t support. For example, a release before 0.4.0 ignores upstream domains, so REGISTERs to those domains get 404 Unknown Domain until you upgrade again.

Roll back with managed upstreams

If you use managed mode, do the following before you roll back, while the new release still runs and before you remove any key from config.yaml. Keep the gateway default. If config.yaml sets managed_registration and the service doesn’t set PGW_MANAGED_REGISTRATION, set the variable to the same value in /etc/systemd/system/pgw.service, and run sudo systemctl daemon-reload. Otherwise, if the new release restarts after you remove the key and before you stop it, the gateway default changes. Return per-user upstreams to per-device. Skip this if no managed upstream uses per-user registration. An upstream without its own managed_registration uses the gateway default, which is per_user unless PGW_MANAGED_REGISTRATION or managed_registration sets per_device.
1

Leave room at the PBX

Give each user room at the PBX for every device plus the user’s contact, as in Switch to per-user registration. Otherwise the PBX refuses a device’s contact while the user’s contact holds the slot, and the earlier release removes the device after five refusals.If the earlier release also registers one contact per user, its contact differs from the new release’s. Give each user room for one more contact, or remove the users’ contacts at the PBX. Until the new release’s contact expires at the PBX, at most max_expires later, calls that the PBX sends to that contact fail.
2

Switch each upstream back

If the new release still runs, switch each managed upstream to per-device registration.
Wait until the log shows registration of the previous mode removed at the upstream for each user.If the new release doesn’t run, remove the users’ contacts at the PBX, or wait up to the upstream’s max_expires for them to expire. Calls to a user fail until the earlier release registers the user’s devices again, which it does at managed_renewals_per_second devices a second at each upstream.
If the new release didn’t run during the rollback, keep the raised contact limit at the PBX until after the next upgrade. An upstream with its own per_user setting keeps that setting. At its first start, the next upgrade registers that upstream’s users with one contact each, while the PBX still holds the earlier release’s device contacts.

Roll back pgw

1

Remove the settings that the earlier release doesn't know

pgw exits with field <key> not found when config.yaml has a key that it doesn’t know. Remove each key that the earlier release lacks. See Configuration keys by release.
2

Stop pgw and install the earlier release

Install the earlier release over /usr/local/bin/pgw.
3

Restore the copy, only if the database is damaged

Skip this step to roll back in place, which is the normal case. The copy lacks everything added since the upgrade, so devices that registered for the first time since then get no calls until their apps register again.
4

Start pgw

Configuration keys by release

The table lists the release that first accepted each key. To keep a setting for the next upgrade, set its PGW_* environment variable instead. An earlier release ignores variables that it doesn’t know.

Next steps

Release notes

Find the breaking changes in each release between yours and the new one.

Back up, move, or restore pgw

Back up the master key with the data folder, so that a restored copy is readable.