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:
config.yaml, so that a rollback doesn’t need to remove it.
Switch to per-user registration
Switch after pgw has run for at least the upstream’smax_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.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 samedata_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 fromconfig.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.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
/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.