Skip to main content
When you finish this page, pgw checks your apps’ passwords and keeps their registrations at the PBX alive. To decide whether you want this, read Managed mode first.

Before you begin

  • A PBX that pgw can reach, and the addresses that it sends calls from.
  • The password of each SIP account that will register through pgw. pgw needs it to register at the PBX.
  • Room at the PBX for one more contact for each user. See the page for your PBX.
You can’t change the mode of an upstream, and two upstreams can’t share a host. So if you already have a passthrough upstream for the same PBX, delete it first. pgw upstream delete needs --force while devices are registered through the upstream.

Create the upstream and its users

1

Create the upstream in managed mode

The answer shows the new upstream’s id. You need it in the next step.
2

Add a user for each SIP account

pgw reads the password from the variable PGW_USER_PASSWORD, so that the password stays out of your shell history. read -rs asks for the password without showing it:
To load many users, call POST /api/v1/upstreams/{id}/users from your provisioning system, or list them in a tenant file.
3

Register the app

Register the app as before. It keeps the username and password that it used at the PBX, so nothing changes on the phone.

Check that it works

The list shows a binding for 1001. At the PBX, the user has one contact, and its address is pgw’s.

If it doesn’t work

Use a different authentication name

Some PBXs authenticate an extension under another name, such as extension 1001 with the name 1001-auth. Give pgw both. Apps register as 1001, and pgw authenticates to the PBX as 1001-auth:

Manage users

When you disable or delete a user, pgw removes the user’s devices at once, together with the registration at the PBX.

Choose how pgw registers devices

By default, pgw registers one contact for each user and rings the user’s devices itself. To register one contact for each device instead, so that the PBX rings them by its own rules, set --managed-registration per_device:
The change starts within about 5 seconds. pgw registers each user in the new way and then removes the old registration, so the PBX briefly holds both. Before you switch, give each user room at the PBX for the user’s devices plus one. For the setting, see the page for your PBX: Asterisk or FreeSWITCH.
To change how an upstream registers, always run pgw upstream update on the running gateway. Don’t change the managed_registration default in config.yaml and restart, because after a restart pgw can’t remove the previous registrations at the PBX, and they stay until they expire.

Turn off the refresh push

In managed mode, a refresh push only tells pgw that the device is alive. To stop waking the device for that, turn the refresh push off for one app:
Without the push, a sleeping device never contacts pgw, so pgw removes it after 7 days of silence (credential_silence_purge) even when it is alive. Raise that setting if you turn the push off.

Next steps

Sign in with a Bearer token

Let apps register with a token instead of a SIP password.

Serve several domains

Keep users at different customer domains apart on one managed upstream.