- Protect the master key, because it decrypts everything else.
- Open only the ports that pgw needs, and keep the admin API local.
- Tell pgw which addresses your PBX sends from, so that nobody else can send calls through it.
- 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
503withRetry-After: 5. Change it withregister_rate_per_ip.
Protect the master key
The master key is a base64-encoded 32-byte key. pgw reads it from the file thatPGW_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
600or400. 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.
.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
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:* 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’sinvite_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 withRetry-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 fulland doesn’t count new addresses. - A restart of pgw clears every ban.
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 lineregister 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 The filter matches IPv4 addresses. For an IPv6 source,
/etc/fail2ban/filter.d/pgw.conf. The pattern depends on log_format.- text (default)
- json
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.