> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# Serve several SIP domains on one PBX

> List your customers' SIP domains on one upstream, so that pgw sends registrations for all of them to the same PBX.

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](https://docs.pgw.sipmicro.services/pbx/kamailio-user-source.md) 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 `*`:

> [tab] CLI
>
> ```bash theme={null}
> pgw upstream update --id <upstream-id> --domains 'acme.example.com,globex.example.com'
> ```
>
> `--domains` replaces the whole list. To create a new upstream with domains, pass the same flag to `pgw upstream create`.

> [tab] Tenant file
>
> ```yaml theme={null}
> upstreams:
>   - name: office
>     host: pbx.example.com
>     invite_source_cidrs: [192.0.2.10/32]
>     domains:
>       - acme.example.com
>       - globex.example.com
> ```

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

| Symptom | Cause and fix |
| - | - |
| REGISTER gets `404 Unknown Domain` | No upstream serves the name that the app registered to. Compare the app's domain with the list. |
| The update fails with `409` and `is already served by another upstream` | Another upstream, yours or another tenant's, already lists the name. A name belongs to one upstream. |
| The update fails with `400` | The wildcard is too broad. pgw refuses a wildcard on a public suffix, such as `*.com` or `*.co.uk`, and on a single label, such as `*.lan`. |
| The update fails with `409` and `every user of an upstream with domains needs a domain` | The upstream is in managed mode and already has users. See [Add domains to an upstream that has users](#add-domains-to-an-upstream-that-has-users). |

## 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:

```bash theme={null}
pgw user create --upstream <upstream-id> --username 1001 --domain acme.example.com
pgw user create --upstream <upstream-id> --username 1001 --domain globex.example.com
```

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:

```bash theme={null}
pgw user revoke --upstream <upstream-id> 1001@acme.example.com
```

### 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:

```text theme={null}
pgw: PATCH /api/v1/upstreams/<upstream-id>: 409 Conflict: every user of an upstream with domains needs a domain that it serves
```

Add the domains and the users' domains in one sync instead.

> [!WARNING]
>
> 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**

```bash theme={null}
pgw config export --out pgw.yaml
```

**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`.

```yaml theme={null}
upstreams:
  - name: office
    host: pbx.example.com
    invite_source_cidrs: [192.0.2.10/32]
    mode: managed
    domains:
      - "*.customers.example.com"
    users:
      - username: "1001"
        domain: acme.customers.example.com
        password_env: PGW_PASSWORD_1001
        enabled: true
```

**3. Preview and apply the change**

`--prune` deletes the users without a domain.

```bash theme={null}
pgw config sync pgw.yaml --prune --dry-run
pgw config sync pgw.yaml --prune --yes
```

**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

> [card] [Set up managed mode](https://docs.pgw.sipmicro.services/upstreams/set-up-managed-mode.md)
>
> Create the users that each domain needs before its apps register.

> [card] [Keep a tenant in a file](https://docs.pgw.sipmicro.services/config-as-code/tenant-file.md)
>
> Change an upstream's domains and users in one reviewed sync.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.