Skip to main content
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. 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.
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.
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.
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.

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.

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

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.

Next steps

Set up alerts

Get an alert when pgw can’t read the Kamailio database.

Troubleshooting

Find the cause when an app can’t register through the user source.