PIA VPN — credentials, port forwarding, and region selection¶
Covers the PIA VPN layer beneath containerized Transmission: where the account credentials live, how to rotate them, how port forwarding is supposed to work, and how to diagnose it when it stops.
For the media-processing pipeline that runs after a download completes, see transmission-filebot.md.
Architecture¶
Transmission runs inside the transmission-vpn container
(haugene/transmission-openvpn) on the transmission-vm Podman machine, owned
by the operator account. All of its traffic egresses through an OpenVPN
tunnel to PIA. If the tunnel drops, the container's killswitch stops traffic
rather than leaking it.
Two separate things are often confused when debugging:
- The tunnel — carries all outbound traffic. When this breaks, nothing reaches the internet at all.
- Port forwarding — asks PIA to open an inbound port so remote peers can connect to us. When only this breaks, downloads still work but run outbound-only.
Credential chain¶
The PIA account password flows through four places. Each one has to be updated during a rotation, in order.
| Stage | Location | Notes |
|---|---|---|
| Source of truth | 1Password item (ONEPASSWORD_PIA_ITEM) |
Read only during prep, on the dev Mac |
| Server storage | Keychain pia-account-<server name, lowercase> |
Stored as username:password, colon-delimited |
| Container input | ~operator/containers/transmission/.env |
Mode 0600, owned operator:staff |
| Runtime | Container environment | Unavoidably plaintext; OpenVPN needs it |
.env is passed with --env-file, never as inline -e flags, so the password
does not appear in ps output on the host.
Rotating the PIA password¶
Do these in order. Skipping step 2 is the usual mistake — the container reads
the keychain-derived .env, not 1Password, so a rotation that stops at
1Password leaves the server authenticating with the old password until the next
full re-provision.
1. Change the password at PIA and in 1Password¶
Rotate it in the PIA account portal, then update the 1Password item so future provisioning runs pick up the new value.
2. Update the keychain on the server¶
On YOUR_SERVER, as the account that owns the entry:
HOST=yourserver # SERVER_NAME from config.conf, in lowercase
security add-generic-password -U \
-s "pia-account-${HOST}" \
-a "${HOST}" \
-w
Omitting a value after -w makes security prompt for it interactively, which
keeps the password out of shell history and the process table. At the prompt,
enter the full colon-delimited pair:
-U updates the existing entry instead of failing on a duplicate.
Verify the entry is present (this prints metadata, not the secret):
3. Regenerate .env and recreate the container¶
This re-reads the keychain, rewrites .env at mode 600, and recreates the
container.
The container must be recreated, not restarted. --env-file is read at
creation time only, so podman restart keeps the old credential in the
existing container's environment.
4. Verify¶
# Tunnel established and egressing through PIA
sudo -u operator podman exec transmission-vpn curl -s https://ipinfo.io/ip
# No auth failures in the log
sudo -u operator podman logs --tail 50 transmission-vpn | grep -i "auth"
A wrong password shows up as AUTH_FAILED in the container log, with the
tunnel repeatedly reconnecting.
Port forwarding¶
PIA's next-generation port forwarding is a two-step flow, implemented in the
image's /etc/openvpn/pia/update-port.sh:
POST https://www.privateinternetaccess.com/api/client/v2/tokenwith the account credentials as form fields, returning a bearer token. Our manager falls back to the legacy/gtoken/generateTokenendpoint (HTTP basic auth) if v2 fails — see Token endpoint outage.GET https://<tunnel-gateway>:19999/getSignaturewith that token, returning a signed payload containing the assigned port, thenbindPortto reserve it.
The assigned port is then pushed into Transmission with
transmission-remote -p <port>.
port_forward=true cannot be trusted¶
PIA publishes a region list at
https://serverlist.piaservers.net/vpninfo/servers/v4 with a per-region
port_forward boolean. That flag is advisory and is known to be wrong.
Verified 2026-08-23: the Panama region advertises port_forward: true while
serving nothing on port 19999 — every host in the region refuses the
connection, including the meta and ovpnudp servers PIA itself advertises
for that region. 103 of 158 regions carry the flag, so it is useful as a
first-pass filter and nothing more.
The only reliable test is to establish a tunnel and ask. That is what
app-setup/templates/pia-pf-probe.sh
does:
podman-transmission-setup.sh deploys it to
~operator/containers/transmission/scripts/pia-pf-probe.sh, next to the port
guard and the post-start hook. Run it from there on the server — that copy
reads the PIA credentials from the sibling .env the container uses, and the
operator account has no repo checkout:
# Probe the default shortlist
ssh operator@your-server ~/containers/transmission/scripts/pia-pf-probe.sh
# Probe specific regions
ssh operator@your-server ~/containers/transmission/scripts/pia-pf-probe.sh ca_vancouver netherlands
# Sweep everything advertising PF (slow — roughly 90s per region)
ssh operator@your-server ~/containers/transmission/scripts/pia-pf-probe.sh --all --out results.csv
From a repo checkout on the server, sudo -u operator
./app-setup/templates/pia-pf-probe.sh works too, provided PIA_ENV_FILE
points at the operator's .env.
The probe runs in its own throwaway container and does not disturb the live
transmission-vpn container or any download in progress.
It reads credentials from the same .env the live container uses and passes
them into the probe container as podman exec -e variables. That does not
keep them out of the process table: the values appear in the host's
podman exec argv, and again in the container's curl argv. The live
manager (transmission-post-start.sh) has the same exposure inside the
container, because curl takes the credentials as arguments.
The probe container runs with --privileged, --device /dev/net/tun, and
CREATE_TUN_DEVICE=false, mirroring the live container. That last one is
load-bearing: Podman already provides the TUN device, and without it the image
tries to create its own, fails with cannot remove '/dev/net/tun': Device or
resource busy, and exits before attempting a tunnel.
Changing regions means setting PIA_VPN_REGION (default ca_vancouver) and
recreating the container.
Region names: image config vs PIA API¶
OPENVPN_CONFIG takes the name of a bundled .ovpn file in the image, which
is not always PIA's API region id. The API calls them nl_amsterdam,
ch_switzerland, and sweden; the image ships netherlands, switzerland,
and se_stockholm.
An unknown name fails quietly from the outside — the container prints its 167-line config list and exits, so anything watching only tunnel state sees a timeout indistinguishable from a dead endpoint. This cost a full survey run on 2026-08-23; five regions reported as failures were fine under their real names.
List the valid names with:
sudo -u operator podman run --rm \
docker.io/haugene/transmission-openvpn:latest ls /etc/openvpn/pia/
Reconciling the two namespaces, and detecting drift as PIA adds or removes endpoints, is tracked in issue #159.
Verified working regions¶
Probed 2026-08-23. Ports are per-session and will differ on reconnect; the point is that each region returned one.
| Region (image config name) | Port | Gateway |
|---|---|---|
ca_toronto |
27251 | 10.17.112.1 |
ca_vancouver |
28284 | 10.7.112.1 |
netherlands |
34475 | 10.13.112.1 |
de_frankfurt |
46014 | 10.135.192.1 |
de_berlin |
32697 | 10.34.192.1 |
switzerland |
47931 | 10.116.192.1 |
romania |
47898 | 10.107.192.1 |
se_stockholm |
43172 | 10.80.192.1 |
panama — the region this server was pinned to until 2026-08-23 — remains the
only one observed serving no port forwarding at all.
Region choice: measure, don't assume¶
YOUR_SERVER runs ca_vancouver, the physically closest endpoint.
Working port forwarding is a prerequisite, not a ranking. All eight regions
above pass that test equally, and the probe deliberately says nothing about
speed. Picking among them by intuition produced a bad answer once already:
ca_toronto was chosen because it was first in a hand-written shortlist and
its probe passed, then measured 4x slower on both metrics.
Measured 2026-08-23, from YOUR_SERVER:
| Region | Latency | Throughput (10 MB) |
|---|---|---|
ca_vancouver |
14.4 ms | 8.6 MB/s |
ca_toronto |
63.2 ms | 2.4 MB/s |
Real-world effect on a well-seeded torrent was the same order: a control magnet that managed 278 kB/s on Toronto pulled 1.83 MB/s on Vancouver.
To compare regions yourself, run a throwaway container on each and measure — the same flags the probe uses:
sudo -u operator podman run -d --name pia-lat-test \
--privileged --device /dev/net/tun:/dev/net/tun \
-e OPENVPN_PROVIDER=PIA -e OPENVPN_CONFIG=<region> \
-e OPENVPN_USERNAME=... -e OPENVPN_PASSWORD=... \
-e CREATE_TUN_DEVICE=false -e LOG_TO_STDOUT=true \
-e TRANSMISSION_DOWNLOAD_DIR=/tmp \
docker.io/haugene/transmission-openvpn:latest
# then, once the tunnel is up:
sudo -u operator podman exec pia-lat-test sh -c '
gw=$(ip route | grep tun | grep -v src | head -1 | awk "{print \$3}")
ping -c 20 -q "$gw" | tail -2
curl -s -o /dev/null -w "%{speed_download} B/s\n" \
https://speed.cloudflare.com/__down?bytes=10000000'
Automating this ranking is what issue #159 is for. Note the jurisdiction constraint recorded there: exclude US endpoints, rank everything else on measured performance.
On the hardcoded PF port¶
update-port.sh targets port 19999 on the tunnel gateway. That number is a
convention from PIA's reference implementation, not something PIA advertises:
their server list publishes ports for every other service (wg 1337, meta
443/8080, ovpnudp 8080/853/123/53) but nothing for port forwarding.
So a refused connection on 19999 proves only that nothing is listening there. Panama failing while eight other regions succeeded makes "Panama serves no PF" the overwhelmingly likely reading — but if PIA ever moves the service, every region would look dead to this script and the probe would report a false negative across the board. Tracked on issue #159.
Diagnosing "torrents won't start"¶
Symptoms and what they mean, in the order worth checking.
Is it the tunnel or just port forwarding?¶
A PIA exit IP means the tunnel is fine and the problem is narrower.
Check the listen port¶
Listen port: 0 means port forwarding failed and took the peer port with
it. This is the failure mode that stops downloads entirely rather than merely
slowing them — see below.
Check whether PF is reachable at all¶
GW=$(sudo -u operator podman exec transmission-vpn sh -c \
"ip route | grep tun | grep -v src | head -1 | awk '{print \$3}'")
sudo -u operator podman exec transmission-vpn \
curl --insecure -s -o /dev/null -w '%{http_code}\n' --max-time 6 \
"https://${GW}:19999/getSignature"
An immediate connection refused (sub-100ms) means the region serves no PF at all. Run the probe script to find one that does.
Known failure mode: empty port zeroes Transmission¶
The upstream image's update-port.sh has an error-handling bug. When
getSignature fails it logs the has been a fatal_error and then continues
anyway, leaving $pf_port empty. That empty value reaches:
which sets Transmission's listen port to 0. It then prints a success banner with a blank port:
With no peer port, tracker announces fail and magnet links cannot retrieve metadata over DHT, so downloads never start. The retry loop repeats this every 15 minutes, re-zeroing the port after any manual fix.
This is strictly worse than doing nothing: an unforwarded Transmission on a valid port still downloads from seeders, just more slowly.
How this is fixed here¶
The bundled updater cannot be patched in place: it lives at
/etc/openvpn/pia/update-port.sh inside the image, alongside the 167 .ovpn
region configs, so mounting over that directory to swap one file would hide
the configs and break region selection.
Instead DISABLE_PORT_UPDATER=true keeps it dormant, and
transmission-post-start.sh
runs our own port-forwarding manager from the already-mounted /scripts
volume. It performs the same token → getSignature → bindPort flow, but hands
the result to
pia-port-guard.sh, which
refuses empty, non-numeric, null, zero, privileged, and out-of-range values
and leaves the existing port intact instead.
If the guard library is missing the manager exits rather than running unguarded — an unforwarded Transmission beats a zeroed one.
Covered by tests/pia-port-guard.bats and
tests/transmission-post-start.bats.
Two container quirks worth knowing¶
The post-start hook is called synchronously. The image backgrounds its own
updater with & but invokes /scripts/transmission-post-start.sh inline. A
hook that blocks — as any lifetime loop does — hangs the rest of the startup
chain, leaving the tunnel negotiated but passing no traffic at all: DNS fails,
curl to a bare IP fails, and Transmission startup script complete never
appears in the log. The manager therefore backgrounds itself immediately and
returns. Diagnose by counting that line:
sudo -u operator podman logs transmission-vpn | grep -c "startup script complete"
# 0 means something in the startup chain is blocking
Peer port randomization fights port forwarding. The image defaults
peer-port-random-on-start to true, which picks a random port at each start
and silently replaces the one PIA assigned. settings.json and the running
listen port then disagree. The setup script now pins
TRANSMISSION_PEER_PORT_RANDOM_ON_START=false.
Token endpoint outage (2026-10-12)¶
After a container recreate at 11:33, every token request failed for over an hour and pia-port-watchdog sent its "port forwarding lost" alert. The tunnel was healthy and the guard kept the existing peer port, so downloads continued unforwarded.
Cause: PIA's legacy /gtoken/generateToken endpoint was answering HTTP 500
with {"status": "ERROR", "message": "server error: all APIs down; please
report bug"} on most calls. The v2 endpoint /api/client/v2/token — the one
PIA's own pia-foss/manual-connections/get_token.sh uses — issued tokens
normally, and getSignature accepts them.
The manager now:
- asks v2 first and falls back to the legacy endpoint;
- retries each token request (
--retry 3), which covers HTTP 500/502/503/504; - logs the HTTP status and PIA's
message, or curl's own error. The earlier version discarded both, so the log could only say "network or auth".
To test the token endpoints by hand from inside the container (prints the status, never the token):
sudo -u operator podman exec transmission-vpn bash -c '
u=$(sed -n 1p /config/openvpn-credentials.txt)
p=$(sed -n 2p /config/openvpn-credentials.txt)
curl -s -o /dev/null -w "v2: %{http_code}\n" \
--form-string "username=$u" --form-string "password=$p" \
https://www.privateinternetaccess.com/api/client/v2/token
curl -s -o /dev/null -w "legacy: %{http_code}\n" -X POST --user "$u:$p" \
https://www.privateinternetaccess.com/gtoken/generateToken'
Monitoring note¶
Port-forwarding loss is not always visible from download activity. Well-seeded torrents continue to work unforwarded via outbound connections, so a monitor that only asks "are downloads moving?" will miss it. Assert on the listen port directly:
Observed 2026-08-21 → 2026-08-23: port forwarding was broken for roughly 47 hours before it was noticed, and only became visible when a newly added magnet link failed to resolve.
Related¶
- Issue #159 — dynamic VPN endpoint selection, including PF verification as a gating criterion
- transmission-filebot.md — the post-download processing pipeline