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

# Configure FreeSWITCH for pgw

> Create a masquerade upstream and allow several contacts for each user, so that FreeSWITCH sends calls for your apps through pgw.

When you finish this page, FreeSWITCH accepts registrations that arrive through pgw and sends the calls for those devices back to pgw. FreeSWITCH needs no module and no patch.

## How FreeSWITCH routes calls to pgw

pgw normally asks a PBX to route calls through it with a Path header. FreeSWITCH ignores Path, so it would send each call straight to the phone, which is asleep.

With the `masquerade` contact strategy, pgw registers its own address as the device's contact. FreeSWITCH then sends every call for the device to pgw, and pgw knows from the contact which device the call is for.

## Before you begin

* FreeSWITCH with a SIP profile that your users register to. The examples use the `internal` profile.
* The addresses that FreeSWITCH sends calls from. See [Allow the PBX to send calls to pgw](https://docs.pgw.sipmicro.services/security.md#allow-the-pbx-to-send-calls-to-pgw).

## Configure the SIP profile

**1. Create the upstream with masquerade**

You choose the contact strategy when you create the upstream, and you can't change it later:

```bash theme={null}
pgw upstream create --name freeswitch --host pbx.example.com --contact-strategy masquerade --invite-source-cidrs 192.0.2.10/32
```

If you already created the upstream without `masquerade`, delete it with `pgw upstream delete --id <id> --force` and create it again. `--force` also removes the upstream's devices from pgw, and they return when their apps next register.

**2. Allow several contacts for each user**

By default, a new registration for a user replaces the previous one, so a second device would log the first one out. In the profile, such as `/etc/freeswitch/sip_profiles/internal.xml`, make FreeSWITCH keep a separate registration for each contact:

```xml theme={null}
<param name="multiple-registrations" value="contact"/>
```

In managed mode, pgw by default registers one contact for each user and rings the devices itself, so you can skip this step unless the upstream uses `per_device`.

**3. Restart the profile**

The restart ends the calls in progress on the profile, so choose a quiet moment.

```bash theme={null}
fs_cli -x "sofia profile internal restart"
```

## Check that it works

Register the app through pgw, then list pgw's bindings:

```bash theme={null}
pgw binding list
```

The list shows a binding for the account. Close the app and call the account from another phone. The app rings.

## If it doesn't work

| Symptom | Cause and fix |
| - | - |
| REGISTER gets `502 Bad Gateway` with `Warning: 399 pgw "upstream did not keep the Path"` | The upstream uses the default `path` strategy. Create it again with `--contact-strategy masquerade`. |
| A second device logs the first one out | `multiple-registrations` isn't set to `contact` in the profile that the apps register to. |
| A wrong password gets `403 Forbidden`, not `401` | This is how FreeSWITCH answers. pgw counts it toward the [REGISTER ban](https://docs.pgw.sipmicro.services/security.md#register-ban), as it counts a `401`. |
| Calls get `403 Forbidden` from pgw | FreeSWITCH sends from an address that isn't in the upstream's `invite_source_cidrs`. |

For other symptoms, see [Troubleshooting](https://docs.pgw.sipmicro.services/troubleshooting.md).

## Next steps

> [card] [Configure apps for pgw](https://docs.pgw.sipmicro.services/apps/overview.md)
>
> Register your app's push credentials, so that pgw can wake the app.

> [card] [Managed mode](https://docs.pgw.sipmicro.services/upstreams/managed-mode.md)
>
> Let pgw check passwords and renew each registration at FreeSWITCH.


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