init, serve, and version calls the admin API. Such a command fails when the API doesn’t answer within 30 seconds, or 3 minutes for pgw config sync.
Commands
Most commands that call the admin API print its answer as JSON.
bootstrap prints the API key, app export-vapid-key prints the key in PEM, cert reload, ban lift, and user revoke print one line, config export prints YAML, config sync prints its plan, and the delete commands print nothing.
A command exits with status 0 when it succeeds, 1 when it fails, and 2 when its arguments or flags are wrong. pgw writes each error to standard error, after pgw: :
The .env file
Every command exceptpgw init, pgw version, and an unknown command reads the PGW_ lines of .env in the current folder, as if you had exported them. So a PGW_KAMAILIO_PASSWORD line in .env replaces the stored password on every pgw upstream update, and a PGW_USER_PASSWORD line sets the password on every pgw user create. After pgw bootstrap, .env also holds PGW_API_KEY.
A variable that your shell sets to a non-empty value wins over .env, and pgw warns your shell overrides <name> from .env. The master key and the master key file count as one setting, so when the shell sets either, pgw reads neither from .env.
pgw init
pgw init writes three files to the current folder and prints the commands to run next. It doesn’t read .env, and it prints no secret.
Without
--force, pgw init writes nothing and fails when any of the three files exists. The error names the files, and when .env is one of them, it says that --force replaces .env whole.
Even with --force, pgw init fails when data/pgw.db exists or the data_dir that config.yaml names holds a pgw.db, because a new master key can’t open that database. The error names the folder. Delete it to start over. pgw init ignores a config.yaml that it can’t read.
Flags for commands that call the API
pgw app create
pgw upstream create
pgw upstream update
pgw upstream update --id <id> takes these flags, with the meanings in pgw upstream create: --name, --port, --transport, --max-expires, --invite-source-cidrs, --domains, --keepalive-seconds, --strict-path=true or --strict-path=false, --managed-registration, --app-auth, the --bearer- flags, and the --kamailio- flags other than --kamailio-use-domain. It changes only the fields whose flags you give, and fails with set at least one field to change when you give none.
--managed-registrationtakesper_user,per_device, ordefaultto use the gateway setting.--app-auth digestremoves the stored issuer, audience, and key set URL, and refuses--bearer-flags. A change tobearerorbothneeds all three--bearer-values, given or stored.- When
PGW_KAMAILIO_PASSWORDis set, it replaces the database password, even without a flag. When a Kamailio setting or the password changes, pgw connects to the database and reads its tables first, as it does on a create. --invite-source-cidrs ""removes every prefix. Only an upstream whose host is an IP address accepts it.--domainsreplaces the list of domains, and--domains ""removes them all.- The host, mode, contact strategy, realm, user source, and
--kamailio-use-domaincan’t change. To change one, delete the upstream and create it again.
pgw config sync
pgw config sync <file> reads the YAML file and the secrets that it references, and sends them to the API. The file is the only argument, and the flags can come before or after it. An _env reference in the file can name a PGW_ variable that .env holds. A name without the PGW_ prefix resolves only from the real environment. For the file format, see Keep a tenant in a file.
pgw always plans first. When the plan is empty, pgw prints
nothing to change. Otherwise it prints one line for each change, indented by two spaces, then the counts.
The key of an app is
<platform>/<bundle_id>, of an upstream its host, and of a user <host>/<username>.
After the plan, pgw applies it and prints applied, unless:
--dry-runis set. pgw stops after the plan.- The plan deletes and
--yesisn’t set. pgw asksApply these changes? [y/N]. Onlyyoryesapplies the plan. Any other answer printspgw: nothing appliedand exits with status 1. Without a terminal, pgw doesn’t ask. It printspgw: deleting needs confirmation; run in a terminal or pass --yesand exits with status 1.
Every other error leaves the tenant unchanged and prints the API’s message.
Next steps
Settings
Look up the settings and
PGW_* variables that pgw serve reads.Keep a tenant in a file
Write the YAML file that
pgw config sync reads.