pgw serve setting in an optional YAML file or in an environment variable. To name the file, run pgw serve --config <path>. Without --config, pgw reads config.yaml from the folder where you run it, if it exists. At startup, pgw logs the file that it read, or none.
- A named file must exist, hold one YAML document, and contain only known keys.
- Environment variables, from the shell or the
.envfile, override the file. See The .env file for the order. - pgw uses the default only for a key that neither source sets. A key set to
0keeps that value. A value outside the range stops pgw at startup with a message that names the key. - A duration is a number with a unit, such as
100ms,30s,10m, or168h. Write zero as0s. - A list variable, such as
PGW_WEBPUSH_HOSTS, takes its entries separated by commas. - A true or false variable takes
trueorfalse, or1or0.
Network and names
| YAML key | Environment variable | Default | Range | Description |
|---|---|---|---|---|
hostname | PGW_HOSTNAME | None. Required. | Not empty | The name in the Via and Record-Route toward the apps. Unless you set upstream_hostname, also the name in Path, Via, and Record-Route toward the PBX. Apps, and the PBX unless you set upstream_hostname, must reach pgw at this name. |
app_listen | PGW_APP_LISTEN | 0.0.0.0:5061 | host:port, port from 1 to 65535 | The TLS listener for apps. |
app_wss_listen | PGW_APP_WSS_LISTEN | None. Off. | Empty, or host:port | The SIP over secure WebSocket (WSS) listener for browser apps, such as 0.0.0.0:8443, with the app listener’s certificate. Its port must differ from those of app_listen and upstream_listen, and from admin_listen’s unless the two use different addresses. |
upstream_listen | PGW_UPSTREAM_LISTEN | 0.0.0.0:5060 | host:port, port from 1 to 65535 | The UDP and TCP listener for PBXs. The default is IPv4 only. For a PBX that reaches pgw over IPv6, set [::]:5060. |
upstream_hostname | PGW_UPSTREAM_HOSTNAME | The value of hostname | Any name | The name in Path, Via, and Record-Route toward the PBX. Set it when the PBX reaches pgw at another address than the apps do, such as through NAT or a tunnel. |
upstream_port | PGW_UPSTREAM_PORT | 0 | 0, or from 1 to 65535 | The port in Path, Via, and Record-Route toward the PBX, when a port forward or tunnel exposes upstream_listen on another port. 0 uses the port of upstream_listen. |
admin_listen | PGW_ADMIN_LISTEN | 127.0.0.1:8080 | host:port, port from 1 to 65535 | The REST API, metrics, and health endpoints, over plain HTTP. |
admin_cors_origins | PGW_ADMIN_CORS_ORIGINS | None. Off. | A list of * or origins | The browser origins that may call the REST API, such as the origin of the API playground. See Use the playground. An entry is *, or http:// or https:// with a host, an optional port, and no path. * lets any website open in the browser send requests, which still need the API key. pgw never allows cookies or other credentials, and the metrics and health endpoints never answer other origins. |
Storage and TLS
| YAML key | Environment variable | Default | Range | Description |
|---|---|---|---|---|
data_dir | PGW_DATA_DIR | ./data | A folder path | Holds the SQLite database pgw.db, the lock file pgw.lock, and the self-signed certificate. A relative path starts at the folder where you run pgw. |
tls_cert_file, tls_key_file | PGW_TLS_CERT_FILE, PGW_TLS_KEY_FILE | A self-signed certificate in data_dir | PEM file paths. Set both or neither. | The certificate and key for the app listeners, read at start and again on SIGHUP or pgw cert reload. Without them, pgw serves a self-signed certificate for hostname from selfsigned.crt and selfsigned.key in data_dir. It lasts a year, and pgw creates a new one at startup when the old one has less than 30 days left or doesn’t cover hostname. The app listeners accept TLS 1.2 and later. |
push_event_retention_days | PGW_PUSH_EVENT_RETENTION_DAYS | 7 | From 0 to 36500 | Days to keep push events. pgw deletes older events every 5 minutes. 0 keeps every event. |
Calls
| YAML key | Environment variable | Default | Range | Description |
|---|---|---|---|---|
hold_seconds | PGW_HOLD_SECONDS | 30 | From 1 to 600, and longer than provisional_timeout and app_handshake_timeout | Seconds that pgw holds an INVITE for a sleeping app. |
delivery_mode | PGW_DELIVERY_MODE | provisional | provisional or always_push | How an INVITE reaches an app with an open connection, for Apps without their own mode. See How pgw works. |
provisional_timeout | PGW_PROVISIONAL_TIMEOUT | 3s | At least 100ms, and shorter than hold_seconds | In provisional mode, how long pgw waits for the app’s first response before it holds the call and pushes. |
max_held_per_binding | PGW_MAX_HELD_PER_BINDING | 8 | From 1 to 1000, and at most max_held_invites | Calls held at once for one sleeping device. A call over the limit gets 486 Busy Here, so the PBX can send it to voicemail. |
max_held_invites | PGW_MAX_HELD_INVITES | 10000 | From 1 to 1000000 | Calls held at once in total. A call over the limit gets 503 with Retry-After: 5. |
max_bindings_per_aor | PGW_MAX_BINDINGS_PER_AOR | 10 | From 1 to 1000 | Devices per SIP account. Over the limit, pgw removes the device that registered least recently, at pgw and at the PBX, and logs binding removed: its AOR reached max_bindings_per_aor. A device that registers again counts once. |
App connections
| YAML key | Environment variable | Default | Range | Description |
|---|---|---|---|---|
app_max_connections | PGW_APP_MAX_CONNECTIONS | 250000 | From 1 to 10000000 | App connections open at once, TLS and WSS together. pgw closes a connection over the limit as soon as it accepts it. Keep it at least 1,000 below the open-file limit. At startup, pgw raises its soft open-file limit to the hard limit, and warns when the hard limit is lower than this setting plus 1,000. See Tune the host. |
app_handshake_timeout | PGW_APP_HANDSHAKE_TIMEOUT | 10s | From 1s to 60s, and shorter than hold_seconds | How long a new app connection has to finish TLS and send its first SIP bytes, and over WSS its whole WebSocket upgrade request, before pgw closes it. |
app_idle_timeout | PGW_APP_IDLE_TIMEOUT | 0s | 0s, or from 30s to 24h | How long an app connection can stay silent before pgw closes it. Any byte, a CRLF keepalive included, restarts the time. 0s never closes a silent connection, which suits apps that sleep for hours. Otherwise, set it above your apps’ keepalive interval. |
app_request_rate_per_binding | PGW_APP_REQUEST_RATE_PER_BINDING | 5 | From 0 to 1000, fractions allowed | Requests per second that one device can send toward its PBX, such as calls, messages, and in-dialog requests, ACK excluded. Over the limit, the request gets 503 with Retry-After: 1. Raise it for apps that send DTMF as SIP INFO. 0 turns the limit off. |
app_request_burst_per_binding | PGW_APP_REQUEST_BURST_PER_BINDING | 20 | From 1 to 10000 | Requests one device can start at once before app_request_rate_per_binding applies. |
REGISTER limits and bans
| YAML key | Environment variable | Default | Range | Description |
|---|---|---|---|---|
register_rate_per_ip | PGW_REGISTER_RATE_PER_IP | 5 | From 0 to 1000, fractions allowed | REGISTERs per second from one source address. An IPv6 address counts by its /64. 0 turns the limit off. |
register_auth_failures | PGW_REGISTER_AUTH_FAILURES | 10 | From 0 to 1000 | REGISTERs from one source address that the PBX, or pgw in managed mode, can refuse for bad credentials within register_auth_failure_window before pgw bans the address for register_ban. An IPv6 address counts by its /64. 0 turns the ban off. |
register_auth_failure_window | PGW_REGISTER_AUTH_FAILURE_WINDOW | 10m | From 1s to 24h | How long a refused password counts toward the ban. pgw checks the range even when the ban is off. |
register_ban | PGW_REGISTER_BAN | 15m | From 1s to 24h | How long pgw refuses REGISTERs from a banned address. pgw checks the range even when the ban is off. |
Pushes
| YAML key | Environment variable | Default | Range | Description |
|---|---|---|---|---|
call_push_rate_per_binding | PGW_CALL_PUSH_RATE_PER_BINDING | 10 | From 0 to 600 | Call and missed-call pushes per minute, not per second, to one device. Over the limit, a call gets 486 Busy Here without a push, and pgw drops the missed-call push. 0 turns the limit off. |
call_push_burst_per_binding | PGW_CALL_PUSH_BURST_PER_BINDING | 5 | From 1 to 100 | Call and missed-call pushes one device can get at once before call_push_rate_per_binding applies. |
push_workers | PGW_PUSH_WORKERS | 64 | From 1 to 4096, and at most push_queue_size | Pushes in flight at once to each of APNs, FCM, and Web Push. One browser push service gets at most half of the Web Push workers, so one that stops answering can’t hold up the others. |
push_queue_size | PGW_PUSH_QUEUE_SIZE | 1024 | From 16 to 1000000 | Pushes that wait for a free worker, per push service, in separate queues for calls and refreshes. When the call queue is full, the call gets 480 Temporarily Unavailable at once. Refresh pushes wait for room. |
webpush_hosts | PGW_WEBPUSH_HOSTS | fcm.googleapis.com, updates.push.services.mozilla.com, web.push.apple.com, *.notify.windows.com | A list of host names, IP addresses, or *. and a host name, each with an optional :port | The push services that a browser’s subscription can name. *. matches any subdomain. An entry without a port matches only port 443. pgw answers a REGISTER whose subscription names another host with 400, and sends no push to it. An empty list turns Web Push off. |
refresh_workers | PGW_REFRESH_WORKERS | 64 | From 1 to 4096 | Refresh pushes in flight at once. After a restart, many devices can be due together. |
Managed mode
| YAML key | Environment variable | Default | Range | Description |
|---|---|---|---|---|
managed_renewals_per_second | PGW_MANAGED_RENEWALS_PER_SECOND | 20 | From 1 to 10000 | The most managed mode renewals per second at one upstream. After a restart, every managed device is due at once. |
credential_silence_purge | PGW_CREDENTIAL_SILENCE_PURGE | 168h | From 1h to 8760h | How long a managed mode device can go without registering before pgw removes it and its registration at the PBX. The user and password stay. |
managed_registration | PGW_MANAGED_REGISTRATION | per_user | per_user or per_device | How pgw registers managed devices at the PBX, for upstreams without their own value. per_user registers one contact per user and pgw rings the devices. per_device registers each device. Don’t change it across a restart while a managed upstream uses it. See Choose how pgw registers devices. |
managed_refresh_push | PGW_MANAGED_REFRESH_PUSH | true | true or false | Whether managed mode iOS and Android devices get a refresh push before their registration with pgw expires, for Apps without their own value. With the push off, a sleeping device sends no REGISTER, and pgw removes it after credential_silence_purge even when it is alive. |
Logging
| YAML key | Environment variable | Default | Range | Description |
|---|---|---|---|---|
log_level | PGW_LOG_LEVEL | info | debug, info, warn, or error | The lowest level that pgw logs. |
log_format | PGW_LOG_FORMAT | text | text or json | text writes key=value fields for journalctl. json writes one JSON object per line, for log collectors. |
log_color | PGW_LOG_COLOR | auto | auto, journald, ansi, or off | How a line shows its level. journald prefixes a syslog priority, so journalctl colors errors and journalctl -p filters by level. ansi colors text for a terminal. off writes plain lines. auto picks journald when systemd sends output to the journal, ansi on a Linux or macOS terminal unless NO_COLOR is set, and off otherwise. |
sip_log | PGW_SIP_LOG | false | true or false | Logs every SIP message that pgw sends and receives, with secrets masked. Needs log_level: debug. At any other level, pgw logs no messages and warns at startup. When the log falls behind, pgw drops messages rather than slow SIP, and counts them in pgw_sip_log_dropped_total. |
sip_log_format | PGW_SIP_LOG_FORMAT | text | text or json | text writes each message as a plain-text block between log lines. json writes each message as one log line in the log_format format. For a collector that reads one JSON object per line, set both keys to json. |
Secrets
These settings have no YAML key. Set them in the shell or the.env file. A configuration file that sets one, such as bootstrap_token, fails as an unknown key.
| Environment variable | Default | Range | Description |
|---|---|---|---|
PGW_MASTER_KEY or PGW_MASTER_KEY_FILE | None. Required. | 32 bytes, base64-encoded | The key that encrypts stored credentials. Set one of the two. pgw doesn’t start when both are set. pgw trims whitespace from the file, not from PGW_MASTER_KEY. Except on Windows, pgw refuses a key file that its group or other users can access. Use mode 600. |
PGW_BOOTSTRAP_TOKEN | None | At least 32 characters | The token that pgw bootstrap, pgw cert reload, and the pgw ban commands present. Without it, pgw refuses those requests. |
Push services for testing
These settings send pushes to a mock push service instead of APNs and FCM, so that you can test a client app. They have no YAML key.Don’t set these variables in production. Every push, with its device token, goes to the named host. pgw logs
push services replaced, for testing at startup when any of them is set.| Environment variable | Default | Range | Description |
|---|---|---|---|
PGW_APNS_HOST | None | A host or host:port | Replaces api.push.apple.com and api.sandbox.push.apple.com. pgw connects over HTTP/2 with TLS. |
PGW_FCM_ENDPOINT | None | An https URL | Replaces https://fcm.googleapis.com. pgw also fetches FCM access tokens from the URL’s /token path. |
PGW_PUSH_CA_FILE | None | A PEM file that holds at least one certificate | Extra certificates that pgw trusts for pushes, such as a mock’s self-signed certificate. pgw doesn’t start when the file holds none. |
Example
/etc/pgw/config.yaml:
hostname: pgw.example.com
data_dir: /var/lib/pgw
tls_cert_file: /etc/pgw/tls/fullchain.pem
tls_key_file: /etc/pgw/tls/privkey.pem
hold_seconds: 30
log_level: info
pgw init writes a config.yaml that sets hostname and data_dir and lists every other setting, commented out, with its default.
Next steps
The .env file
Check which source wins when the shell,
.env, and the configuration file set the same setting.Tune the host
Raise the open-file limit before you raise
app_max_connections.