Gateway command line
Check, troubleshoot and update a gateway from its host with pulseha-gateway.
Every gateway host has the pulseha-gateway command. Use it to see what the gateway is doing, find out why it is not working, read its log and request an update. This page lists the commands, the exit codes scripts can rely on, and the rules every command follows. Each command also has built-in help (pulseha-gateway status --help) and a man page (man pulseha-gateway-status).
This page describes gateway 2.20.0 or later. Check the version on the host with pulseha-gateway version --short. An older gateway does not have logs, peers, restart, config show, update check, update apply, drain --status, login --force or the exit codes 5, 6 and 7, and answers a command it does not know with exit code 2. Update it from the console once PulseHA offers 2.20.0 for it, and until then use the commands in On a gateway older than 2.20.0.
Most commands need sudo: the gateway’s state is readable by root only. A command run without it says so and prints the exact command to run instead.
Commands#
| Command | What it does | Changes anything |
|---|---|---|
status | What the running gateway is doing: service health, the connection to PulseHA, the last configuration sync and policy, the malware scanner, the access record queue, TLS inspection, the update on offer and the version. Each fact shows how old it is. | No |
doctor | Checks the host, grouped by area, and gives a fix for every warning and failure. | No |
peers | The devices configured on the tunnel, and which are connected (a handshake in the last five minutes). | No |
logs | The gateway’s log. -f follows it, -n 200 shows the last 200 entries, --since "1 hour ago" starts at a time. --unit update shows the update log and --unit scanner the malware scanner’s. | No |
config show | The configuration the gateway runs with and where each value came from. Secrets show as <redacted>. | No |
update check | Whether the gateway can be updated remotely, and the release PulseHA offers it. | No |
update apply | Asks PulseHA to update the gateway to the offered release, then follows the update. | Yes |
restart | Restarts the gateway service and waits until it is healthy. Connected devices lose their tunnel for a few seconds. | Yes |
drain | Waits for connected devices to leave before you take the gateway out of service. drain --status only reports. | Yes, except --status |
login | Enrolls the gateway. --force replaces an existing enrollment. | Yes |
logout | Removes the gateway’s enrollment and stops the service. | Yes |
version | The installed version. | No |
The read-only commands never start, stop or change anything, so they are safe to run at any time, including on a gateway that is serving traffic.
Check a gateway#
sudo pulseha-gateway status
sudo pulseha-gateway doctor
status ends with a verdict. Values it reads from the running service are labelled with their age (for example “as of 12s ago”) and can trail the live state by one heartbeat, about 10 seconds. If the service has not reported yet, for example just after it started, those values read unknown.
doctor groups its checks under System, Dependencies, WireGuard, Enrollment, Control connection, Service, Scanner, Access records, Updates and Proxy and inspection. Each line reads ok, warn or fail, and every warn and fail has a fix: line under it. It exits 1 when a check failed.
Use it from scripts#
Add --json to any command to get one JSON document on standard output. Use the JSON, not the text: the wording of the text can change in any release, while JSON fields are only ever added.
- When a command fails, standard output is empty and the reason is one
Error:line on standard error.pulseha-gateway peers --json | jqeither gets a document or nothing. status --jsonexits 0 whenever it prints a document. Readgateway.registered,service.runningandservice.healthyinside it.- In
doctor --json, each check has a stableid, itsgroup,status(ok,warnorfail) and afix. logs --jsonprints one JSON object per line, withtime,unit,priorityandmessage.
Output is coloured only on a terminal. --no-color or the NO_COLOR environment variable turns colour off everywhere. Without a terminal nothing prompts: a command that would ask for confirmation stops with exit code 2 and names the flag that skips the question (--force for logout, --yes for update apply).
Exit codes#
| Code | Meaning |
|---|---|
0 | Success. |
1 | The command failed. The reason is on standard error. doctor also exits 1 when a check failed. |
2 | Usage mistake: an unknown command, flag or argument, or a confirmation was needed with no terminal to ask on. |
3 | login found the gateway already enrolled and changed nothing. |
4 | Never returned by the command. It is the installer’s “enrolled, but not running”. |
5 | The command must run as root. Run it again with sudo. |
6 | The gateway is not enrolled. |
7 | The gateway service is not running or not healthy. |
Plain pulseha-gateway status exits 7 when the gateway service is stopped or unhealthy. Earlier releases exited 0 on any enrolled gateway, so a script that runs pulseha-gateway status && ... now stops on a gateway that is down. If the script only needs to know that the gateway is enrolled, use pulseha-gateway status --json, which exits 0 whenever it prints a document, and read gateway.registered.
A code never changes meaning. The installer has its own codes, listed in Enroll a gateway.
Read the log#
Needs gateway 2.20.0 or later. On an older gateway, see On a gateway older than 2.20.0.
sudo pulseha-gateway logs -n 200
sudo pulseha-gateway logs -f
sudo pulseha-gateway logs --unit update --since "1 hour ago"
The log can contain personal data: device names, user names, IP addresses and the web addresses users visited. Handle it accordingly, and share it only through your organisation’s approved support channel.
Update a gateway#
Needs gateway 2.20.0 or later. On an older gateway, see On a gateway older than 2.20.0.
A gateway installed from the PulseHA package can be updated from the console (open it in Network → Gateways and choose Update to <version>) or from the host:
sudo pulseha-gateway update check
sudo pulseha-gateway update apply
update check shows the release PulseHA offers this gateway and how long ago it said so. It makes no network request. update apply asks PulseHA to start that update and follows it until it finishes. You cannot choose a different version. The update is the same one the console starts: PulseHA verifies the package before it is installed, waits for connected devices to leave, checks the gateway is healthy afterwards and rolls back if it is not. Each release is tried at most twice on a gateway.
Requests from the gateway host are off until PulseHA turns them on. Until then update apply exits 1 and tells you to request the update from the console.
update apply and restart both refuse while an update is already running.
Re-enroll a gateway#
Needs gateway 2.20.0 or later. On an older gateway, see On a gateway older than 2.20.0.
login on a gateway that is already enrolled changes nothing and exits 3. To replace the enrollment, for example after the gateway was removed in the console, create a new code under Network → Gateways → Add Gateway and run:
sudo pulseha-gateway login --force --code phgw_...
The gateway backs up its current enrollment and checks the copy before it removes anything. If the new code is refused, the old enrollment is put back and the service started again. A code that was accepted but could not be saved is used up: create another.
Running login without sudo on a gateway installed from the package stops with exit code 5 before the code is sent, so the single-use code is not wasted.
Take a gateway out of service#
Needs gateway 2.20.0 or later. On an older gateway, see On a gateway older than 2.20.0.
sudo pulseha-gateway drain --stop
sudo pulseha-gateway drain --status
drain --stop waits for connected devices to leave (up to --timeout, 60 seconds by default), then stops the gateway service. The gateway shows as Offline in the console until you start it again with sudo systemctl start pulseha-gateway.
Shell completion#
Needs gateway 2.20.0 or later. On an older gateway, see On a gateway older than 2.20.0.
The package installs completion for bash, zsh and fish. Open a new shell after installing and press Tab after pulseha-gateway. On another shell, pulseha-gateway completion --help explains how to load it.
On a gateway older than 2.20.0#
Gateways before 2.20.0 have status, doctor, login, logout, drain, update status and version, without the additions on this page. Until the gateway is updated, use these instead:
| On 2.20.0 or later | On an older gateway |
|---|---|
sudo pulseha-gateway logs -f | sudo journalctl -u pulseha-gateway -f |
sudo pulseha-gateway peers | sudo pulseha-gateway status --peers-only |
sudo pulseha-gateway restart | sudo systemctl restart pulseha-gateway, then sudo systemctl status pulseha-gateway |
sudo pulseha-gateway update check and update apply | The console: open the gateway in Network → Gateways and choose Update to <version> |
sudo pulseha-gateway login --force --code phgw_... | sudo pulseha-gateway logout --force, then sudo pulseha-gateway login --code phgw_.... There is no backup: if the new code is refused, the gateway stays unenrolled until you enroll it with another code. |
sudo pulseha-gateway drain --stop | sudo systemctl stop pulseha-gateway. The service removes its tunnel and rules when it stops; connected devices move to another gateway. |
sudo pulseha-gateway drain --status | No equivalent. sudo pulseha-gateway status --peers-only shows which devices are still connected. |
sudo pulseha-gateway config show | No equivalent. The settings are in /etc/pulseha/gateway.env and the gateway’s configuration file; they hold secrets, so never paste them into a ticket or chat. |
pulseha-gateway completion bash (and zsh, fish) | The same command works, but the package does not install the scripts; see pulseha-gateway completion --help. |
sudo pulseha-gateway doctor | sudo pulseha-gateway doctor gives a flat list of checks without fixes. Read the log with journalctl as above. |
On an older gateway every failure other than a usage mistake (2) and login on an enrolled gateway (3) exits 1, and only status, doctor, update status and version take --json. Do not run status there as a check that changes nothing: before 2.20.0 it could create the gateway’s WireGuard key file.