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.
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.
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 To accept every customer under one name without listing each, use a wildcard, such as
*:- CLI
- Tenant file
--domains replaces the whole list. To create a new upstream with domains, pass the same flag to pgw upstream create.'*.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 at1001@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:- Each domain’s DNS record points at pgw.
- pgw’s certificate covers every domain, because pgw serves one certificate to all apps. A wildcard certificate covers one level:
*.customers.example.comcoversa.customers.example.com, but noteu.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: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. Sopgw upstream update --domains fails on an upstream that already has users:
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.
- List the upstream’s users with
pgw user list --upstream <upstream-id>. - 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. - Remove the domain with
pgw upstream update --domains.
--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.