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

# Set up managed mode

> Create a managed upstream, add a user for each SIP account, and manage those users.

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](https://docs.pgw.sipmicro.services/upstreams/managed-mode.md) 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**

```bash theme={null}
pgw upstream create --name office --host pbx.example.com --mode managed --invite-source-cidrs 192.0.2.10/32
```

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:

```bash theme={null}
read -rs PGW_USER_PASSWORD && export PGW_USER_PASSWORD
pgw user create --upstream <upstream-id> --username 1001
unset PGW_USER_PASSWORD
```

To load many users, call `POST /api/v1/upstreams/{id}/users` from your provisioning system, or list them in a [tenant file](https://docs.pgw.sipmicro.services/config-as-code/tenant-file.md).

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

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

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

| Symptom | Cause and fix |
| - | - |
| The app gets `401` again and again | The password in pgw differs from the one in the app. Set it again with `pgw user set --id <user-id> --password`. |
| The app gets `502 Bad Gateway` | The PBX refused pgw's own registration: the stored password is wrong at the PBX, or the user has no free contact there. See [Troubleshooting](https://docs.pgw.sipmicro.services/troubleshooting.md#register-gets-502-bad-gateway). |
| The app gets `403 Forbidden` | The app authenticates with a username that differs from the user part of its SIP address. Set the app's authentication username to the same value, such as `1001`. |

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

```bash theme={null}
pgw user create --upstream <upstream-id> --username 1001 --auth-username 1001-auth
```

## Manage users

| Task | Command |
| - | - |
| Change a password, after you change it at the PBX | `pgw user set --id <user-id> --password`, with the new password in `PGW_USER_PASSWORD` |
| Disable a user | `pgw user set --id <user-id> --enabled=false` |
| Delete a user | `pgw user delete --id <user-id>` |
| Sign out a user's devices | `pgw user revoke --upstream <upstream-id> 1001` |

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

```bash theme={null}
pgw upstream update --id <upstream-id> --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](https://docs.pgw.sipmicro.services/pbx/asterisk.md#leave-room-for-one-more-contact) or [FreeSWITCH](https://docs.pgw.sipmicro.services/pbx/freeswitch.md#configure-the-sip-profile).

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

```bash theme={null}
pgw app set-managed-refresh-push --id <app-id> --value off
```

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

> [card] [Sign in with a Bearer token](https://docs.pgw.sipmicro.services/upstreams/bearer-tokens.md)
>
> Let apps register with a token instead of a SIP password.

> [card] [Serve several domains](https://docs.pgw.sipmicro.services/upstreams/several-domains.md)
>
> Keep users at different customer domains apart on one managed upstream.


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