Skip to main content
Example Corp starts hosting two customers on its PBX. Their users register as 1001@acme.example.com and 1001@globex.example.com, and both must reach the PBX at pbx.example.com. When you finish this page, one upstream serves pbx.example.com, acme.example.com, and globex.example.com.

How pgw picks the upstream

pgw reads the domain that an app registers to and looks for the upstream that serves it. An upstream serves these names:
  • Its host, which is also the address that pgw sends to.
  • Its domains, a list of other names. An entry is a DNS name, or a wildcard such as *.customers.example.com, which matches every name under it.
An exact name always wins over a wildcard, and a longer wildcard wins over a shorter one. A registration to a name that no upstream serves gets 404 Unknown Domain. pgw matches names, not addresses. List a domain even when its DNS record already points at the PBX.

Before you begin

  • An upstream for the PBX, or the values to create one.
  • A PBX that already accepts each domain, as it would if the apps registered to it directly.
An upstream with a Kamailio user source takes no domain list. With use_domain, it reads its domains from Kamailio’s domain table.

Add the domains

1

List the domains on the upstream

Quote the list, so that the shell doesn’t expand a *:
--domains replaces the whole list. To create a new upstream with domains, pass the same flag to pgw upstream create.
To accept every customer under one name without listing each, use a wildcard, such as '*.customers.example.com'.
2

Set the domain in each app

In each app, set the account’s domain to the customer’s domain, such as acme.example.com. The outbound proxy stays pgw’s address.

Check that it works

Register an app at 1001@acme.example.com, then run pgw binding list. The binding’s address of record shows the customer’s domain. At the PBX, the registration arrives for 1001@acme.example.com, so 1001 at Acme and 1001 at Globex stay two accounts.

If it doesn’t work

If apps connect to the customer’s domain

Apps normally use pgw as their outbound proxy, so they connect to pgw’s hostname, and pgw needs a certificate for that name only. If your apps instead connect to the customer’s domain, two more things must be true:
  1. Each domain’s DNS record points at pgw.
  2. pgw’s certificate covers every domain, because pgw serves one certificate to all apps. A wildcard certificate covers one level: *.customers.example.com covers a.customers.example.com, but not eu.a.customers.example.com.

Add users at each domain

In managed mode, pgw holds the users, so it must know which domain each one belongs to. Name the domain when you create the user:
These are two users, each with its own password, devices, and registration at the PBX. pgw registers each user at the PBX in the user’s domain. The REGISTER goes to the upstream’s host, with the Request-URI sip:acme.example.com and the To and From sip:1001@acme.example.com. A PBX that finds an account by its user part alone treats 1001 at both domains as one account. If your PBX can find an account by user and domain, name each account with its domain, such as 1001@acme.example.com. On a PBX that can’t tell the domains apart, give each domain its own usernames. To sign out a user’s devices, name the user with its domain:

Add domains to an upstream that has users

A user on an upstream without domains has no domain, and a user’s domain can’t change. So pgw upstream update --domains fails on an upstream that already has users:
Add the domains and the users’ domains in one sync instead.
The sync deletes every user of the upstream and creates each one again at the user’s domain. pgw removes the users’ devices and their registrations at the PBX, and the devices get no calls until each app registers again. Run the sync when few calls come in.
1

Export the configuration

2

Add the domains to the file

Add domains to the upstream and a domain to each user. Give a user the upstream’s host when you don’t change that user’s apps, or a customer’s domain otherwise. The sync creates the users again, so name each password with password_env or password_file.
3

Preview and apply the change

--prune deletes the users without a domain.
4

Update the apps

For each user that you moved to a customer’s domain, set the account’s domain in the user’s apps.

Remove a domain

pgw upstream update --domains fails with 409 when the new list no longer serves a user’s domain. Delete the domain’s users first.
  1. List the upstream’s users with pgw user list --upstream <upstream-id>.
  2. Delete each user of the domain with pgw user delete --id <user-id>. pgw removes the user’s devices and their registrations at the PBX.
  3. Remove the domain with pgw upstream update --domains.
In a tenant file, remove the domain and its users, and sync with --prune.

Next steps

Set up managed mode

Create the users that each domain needs before its apps register.

Keep a tenant in a file

Change an upstream’s domains and users in one reviewed sync.