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

# Use a Kamailio user source

> Have pgw check app passwords against Kamailio's subscriber table in managed mode, so you keep one list of SIP accounts.

If your SIP accounts already live in Kamailio's database, you don't want to enter them a second time in pgw. With a Kamailio user source, pgw reads each account from the `subscriber` table of Kamailio's `auth_db` module when an app registers. A password that you change in Kamailio works in pgw within a minute, with no step in pgw.

A Kamailio user source is a variant of [managed mode](https://docs.pgw.sipmicro.services/upstreams/managed-mode.md). pgw checks the app's password against the subscriber row, and then registers at Kamailio with the subscriber's credentials. pgw only reads the database and never writes to it.

## Before you begin

* Kamailio with `auth_db` on MySQL, MariaDB, or PostgreSQL.
* A TCP path from the pgw host to the database. pgw doesn't connect over a Unix socket.

## Create the database user

pgw needs to read two tables and nothing else, so give it a database user that can do only that. Replace `192.0.2.20` with the pgw host's address, and the table names if your schema renames them.

> [tab] MySQL or MariaDB
>
> ```sql theme={null}
> CREATE USER 'pgw'@'192.0.2.20' IDENTIFIED BY '<password>';
> GRANT SELECT ON kamailio.subscriber TO 'pgw'@'192.0.2.20';
> GRANT SELECT ON kamailio.domain TO 'pgw'@'192.0.2.20';
> ```

> [tab] PostgreSQL
>
> ```sql theme={null}
> CREATE ROLE pgw LOGIN PASSWORD '<password>';
> GRANT CONNECT ON DATABASE kamailio TO pgw;
> GRANT SELECT ON subscriber, domain TO pgw;
> ```

> [!WARNING]
>
> An `ha1` value works as a password at Kamailio, so treat read access to the subscriber table as access to every account.

## Create the upstream

**1. Put the database password in the environment**

Read the database user's password into `PGW_KAMAILIO_PASSWORD`, which keeps it out of your shell history and the process list.

```bash theme={null}
read -rs PGW_KAMAILIO_PASSWORD && export PGW_KAMAILIO_PASSWORD
```

**2. Create the upstream**

Create the upstream in managed mode with `--user-source kamailio`. Set `--host` to Kamailio's SIP address, and the `--kamailio-` flags to its database.

```bash theme={null}
pgw upstream create --name kamailio --host sip.example.com --mode managed --invite-source-cidrs 192.0.2.10/32 --user-source kamailio --kamailio-driver mysql --kamailio-host db.example.com --kamailio-user pgw --kamailio-database kamailio
unset PGW_KAMAILIO_PASSWORD
```

pgw connects to the database and reads the subscriber table before it creates the upstream, and the domain table too when `use_domain` is on. If one of these checks fails, pgw creates nothing and answers `kamailio check failed:` followed by the check that failed, which is `connect`, `domain table`, or `subscriber table`. The message names only the kind of failure, such as `timeout` or `authentication`, because a database driver's own message can contain the password.

**3. Set up the app**

In the app, use the subscriber's username, password, and domain.

## Check that it works

Register the app, then run `pgw binding list`. The list shows a binding for the subscriber.

If the list is empty, see [Troubleshooting](https://docs.pgw.sipmicro.services/troubleshooting.md).

## Database connection options

pgw connects with TLS and checks the database's certificate by default (`--kamailio-tls verify`). For a database with a self-signed certificate, add `--kamailio-tls require`. On a private network, `--kamailio-tls off` connects over plain TCP. The port defaults to 3306 for `mysql` and 5432 for `postgres`. If your schema renames a table or column, set the matching flag.

| Flag | Default |
| - | - |
| `--kamailio-subscriber-table` | `subscriber` |
| `--kamailio-username-column` | `username` |
| `--kamailio-domain-column` | `domain` |
| `--kamailio-password-column` | `password` |
| `--kamailio-ha1-column` | `ha1` |
| `--kamailio-domain-table` | `domain` |
| `--kamailio-domain-table-column` | `domain` |

### Change the upstream later

You can't change the user source, `use_domain`, or `--realm` later. To change them, delete the upstream and create it again. To change the database settings or the table and column names, run `pgw upstream update`. When `PGW_KAMAILIO_PASSWORD` is set during the update, pgw replaces the stored database password with it. pgw checks the database again before it saves the change.

## Choose use\_domain

Set `use_domain` the way your Kamailio sets it. It is on by default. To turn it off, add `--kamailio-use-domain=false` when you create the upstream.

| | `use_domain` on (default) | `use_domain` off |
| - | - | - |
| Which subscriber pgw reads | The row with the username and the domain of the app's REGISTER | The row with the username |
| Domains that apps register to | The upstream's host, and each domain in the domain table | The upstream's host |
| Digest realm | `--realm` when you set one, else the domain as the domain table stores it | `--realm` when you set one, else the upstream's host |

A Kamailio upstream takes no `--domains`, because the table above already decides which domains it serves.

With `use_domain` on, pgw reads the domain table when it starts and again every 60 seconds, so a new domain works within a minute. Until the first read succeeds, pgw tries again every 5 seconds. If a later read fails, pgw keeps the domains that it read last.

## Match Kamailio's realm

A subscriber with only an `ha1` works only when pgw challenges the app in the realm that the `ha1` was computed with. Kamailio's own scripts use the domain as the realm, which is what pgw uses with `use_domain` on. If your Kamailio challenges with a fixed realm instead, set `--realm` to that realm when you create the upstream.

On a Kamailio upstream, pgw challenges apps with MD5 only, because the `ha1` column holds MD5 hashes.

## Block a user

Change the subscriber's password in Kamailio. Then remove the user's devices from pgw.

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

pgw drops the user's devices for that domain at once and removes their registrations at Kamailio. With `use_domain` off, name the user alone: `pgw user revoke --upstream <upstream-id> 1001`. You can then delete the subscriber's row.

Always revoke, and revoke before you delete the row:

* A changed password alone doesn't drop a device, because pgw renews the registration with the new password.
* A deleted row drops the user's devices only at their next renewal. Kamailio keeps their registrations until they expire, because pgw has no password left to remove them with.

## Let apps sign in with a token

Apps can register with an access token from your own sign-in service instead of the subscriber's password. pgw still registers them at Kamailio with the subscriber's credentials. See [Authenticate apps with a Bearer token](https://docs.pgw.sipmicro.services/upstreams/bearer-tokens.md).

## Exempt pgw from flood protection

Add pgw's address to the allow list of Kamailio's `pike` and `ratelimit` modules. Otherwise Kamailio can block pgw after a restart, and with pgw every device behind it. Every renewal sends Kamailio two REGISTERs from pgw's address: one that Kamailio challenges, and one that answers the challenge. After pgw restarts, it renews up to `managed_renewals_per_second` registrations a second at each upstream, 20 by default.

## Monitor the user source

Watch the `unavailable` result of `pgw_user_source_lookups_total`. A growing count means that pgw can't read the database. Apps then get `500` with `Retry-After: 5`, and pgw keeps their registrations.

pgw also reports the query time in `pgw_user_source_lookup_seconds`, the number of loaded domains in `pgw_kamailio_domains`, and failed reads of the domain table in `pgw_kamailio_domain_load_failures_total`. See [Metrics](https://docs.pgw.sipmicro.services/metrics.md).

## Next steps

> [card] [Set up alerts](https://docs.pgw.sipmicro.services/alerts.md)
>
> Get an alert when pgw can't read the Kamailio database.

> [card] [Troubleshooting](https://docs.pgw.sipmicro.services/troubleshooting.md)
>
> Find the cause when an app can't register through the user source.


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