Skip to main content
pgw is reachable from the internet, it holds the keys that can push to every one of your users, and it sits in front of your PBX’s registrar. Most of its protection is built in and needs no setup. The rest is yours to do:
  1. Protect the master key, because it decrypts everything else.
  2. Open only the ports that pgw needs, and keep the admin API local.
  3. Tell pgw which addresses your PBX sends from, so that nobody else can send calls through it.
  4. Review the REGISTER ban, which stops password guessing against your PBX.

What pgw stores

pgw keeps its records in one database file, pgw.db, in data_dir. Someone who copies pgw.db without the master key gets no push credentials and no passwords.

What pgw does for you

  • It isn’t an open relay. pgw refuses, with 403, any request on the PBX listener that doesn’t come from an upstream’s allowed addresses. A request from an app goes only to that app’s PBX.
  • Push tokens stay inside pgw. pgw removes the push parameters from everything that it sends to the PBX.
  • Logs and API answers carry no secrets. pgw drops tokens, push parameters, and credentials from every log line. The API returns none of them, except a web app’s VAPID key when you export it for a backup. Logs do show each device’s SIP address and its User-Agent, which can contain a name such as Alice's iPhone, so treat them as personal data.
  • Registrations are rate-limited. One source address can send 5 REGISTERs a second, with a burst of 10. Above that, pgw answers 503 with Retry-After: 5. Change it with register_rate_per_ip.

Protect the master key

The master key is a base64-encoded 32-byte key. pgw reads it from the file that PGW_MASTER_KEY_FILE names, or from the variable PGW_MASTER_KEY. It has no setting in config.yaml, so that it never ends up in a configuration repository.
  • Use the file. A variable is inherited by child processes and can appear in crash reports.
  • Set the file’s mode to 600 or 400. pgw refuses to start with a key file that its group or other users can access.
  • Back up the key separately from pgw.db. Someone who holds both can decrypt every stored credential, and someone who holds only one can’t.
If you lose the master key, pgw can’t decrypt the push credentials or the stored passwords. You then start with an empty data_dir and create the tenant, apps, upstreams, and users again.
A test setup keeps the key in a .env file instead, which pgw init creates with mode 600. Keep the file out of version control. Except on Windows, pgw refuses to start with a master key from a .env file that other users can read. See The .env file.

Open only the ports that pgw needs

The admin API has no TLS. Keep admin_listen on 127.0.0.1. To manage pgw from another host, use an SSH tunnel or put a TLS reverse proxy in front of it.

Allow a browser page to call the admin API

A browser blocks a web page from reading the admin API’s answers, because pgw sends no CORS headers by default. To let one page call it, list the page’s origin:
Each request still needs an API key, and pgw never accepts cookies on a cross-origin request. An entry of * allows a page on any site. The setting doesn’t move the API, which stays on admin_listen, without TLS. For the playground in these docs, see Use the playground.

Allow the PBX to send calls to pgw

pgw accepts calls and other requests on the PBX listener only from the addresses in the upstream’s invite_source_cidrs. You can leave the list empty only when the upstream’s host is an IP address. pgw then accepts requests from that address. Any other address gets 403 Forbidden.
1

Set the PBX's addresses

When you create the upstream, list the addresses that the PBX sends from. A PBX cluster needs the address of every node.
2

Find a missing address

If calls get 403 Forbidden, watch the SIP traffic on the pgw host while you call the app. The source address of the INVITE is the one to add.
3

Update the list

Give the whole new list. It replaces the old one, and the change applies at once.

REGISTER ban

The PBX sees every REGISTER come from pgw, so it can’t tell a password guesser from a legitimate device. pgw counts the REGISTERs from each source address that the PBX, or pgw in managed mode, refuses for bad credentials. After 10 within 10 minutes, pgw bans the address for 15 minutes. Its REGISTERs get 503 with Retry-After and don’t reach the PBX. An IPv6 source counts by its /64 prefix.
  • A refresh over a connection that registered the same account, with the same username, still reaches the PBX, so registered devices keep working.
  • Devices behind the same NAT address share the ban. If many devices share an address, raise register_auth_failures.
  • Behind a TCP proxy that hides the devices’ addresses, every device shares the proxy’s address, so set register_auth_failures: 0.
  • pgw tracks at most 65,536 source addresses. While the table is full, pgw logs register ban table full and doesn’t count new addresses.
  • A restart of pgw clears every ban.
To change the ban, set register_auth_failures, register_auth_failure_window, and register_ban. To see the active bans, run pgw ban list. To lift a ban at once, run pgw ban lift --source <address>.

Block banned addresses with fail2ban

pgw’s ban covers only REGISTERs. To block a banned address at the firewall, point fail2ban at pgw’s log line register source banned. Keep the block short. It also cuts off the devices already registered from that address, and a carrier-grade NAT address can hold many users.
1

Create the filter

Create /etc/fail2ban/filter.d/pgw.conf. The pattern depends on log_format.
The filter matches IPv4 addresses. For an IPv6 source, banned_source holds a /64 prefix, such as 2001:db8:1:2::/64, which the filter doesn’t match. Block an IPv6 prefix with a firewall rule of your own.
2

Create the jail

Create /etc/fail2ban/jail.d/pgw.conf. Set bantime to no longer than register_ban.
3

Reload fail2ban

Next steps

Logs

Read the ban and refusal lines that this page names.

Settings reference

Look up the limits on this page, with their defaults and ranges.

Back up, move, and restore pgw

Back up the database and the master key, so that a lost host doesn’t cost the credentials.