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

# Settings reference

> Every setting of pgw serve, with its YAML key, environment variable, default, and allowed range.

Set each `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 `.env` file, override the file. See [The .env file](https://docs.pgw.sipmicro.services/reference/env-file.md) for the order.
* pgw uses the default only for a key that neither source sets. A key set to `0` keeps 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`, or `168h`. Write zero as `0s`.
* A list variable, such as `PGW_WEBPUSH_HOSTS`, takes its entries separated by commas.
* A true or false variable takes `true` or `false`, or `1` or `0`.

## 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](https://docs.pgw.sipmicro.services/api/introduction.md#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](https://docs.pgw.sipmicro.services/how-pgw-works.md#when-the-app-is-still-connected). |
| `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](https://docs.pgw.sipmicro.services/tune-the-host.md). |
| `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](https://docs.pgw.sipmicro.services/upstreams/set-up-managed-mode.md#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.

> [!WARNING]
>
> 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`:

```yaml theme={null}
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

> [card] [The .env file](https://docs.pgw.sipmicro.services/reference/env-file.md)
>
> Check which source wins when the shell, `.env`, and the configuration file set the same setting.

> [card] [Tune the host](https://docs.pgw.sipmicro.services/tune-the-host.md)
>
> Raise the open-file limit before you raise `app_max_connections`.


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