Skip to main content
Every command except 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 except pgw 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-registration takes per_user, per_device, or default to use the gateway setting.
  • --app-auth digest removes the stored issuer, audience, and key set URL, and refuses --bearer- flags. A change to bearer or both needs all three --bearer- values, given or stored.
  • When PGW_KAMAILIO_PASSWORD is 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.
  • --domains replaces the list of domains, and --domains "" removes them all.
  • The host, mode, contact strategy, realm, user source, and --kamailio-use-domain can’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-run is set. pgw stops after the plan.
  • The plan deletes and --yes isn’t set. pgw asks Apply these changes? [y/N] . Only y or yes applies the plan. Any other answer prints pgw: nothing applied and exits with status 1. Without a terminal, pgw doesn’t ask. It prints pgw: deleting needs confirmation; run in a terminal or pass --yes and exits with status 1.
Once pgw starts to apply the plan, the server finishes it even if you interrupt the command. 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.