Configuration handoff¶
Privateerr coordinates with Gluetun through shared files at startup and an authenticated control API during recovery. Gluetun owns the tunnel throughout; the supervisor never treats a rewritten file as proof that a running tunnel has loaded it.
- Privateerr prepares a matching pair. It finishes any interrupted save, then reuses validated files when recovery is enabled or invokes PIA's scripts for fresh configuration.
- Privateerr reports startup readiness. Valid files allow Compose to start Gluetun without waiting for a tunnel that does not exist yet.
- The Gluetun wrapper reads metadata. It exports the matching PIA server name and configures the recovery API role when enabled.
- Gluetun establishes the tunnel. Download clients start inside its network namespace once it is healthy.
- The supervisor monitors sustained failure. It applies a validated replacement through Gluetun's API and saves the files after settings readback and tunnel health confirm success.
Why the metadata exists¶
wg0.conf has the interface, peer, keys, and endpoint. PIA forwarding also needs the provider's server identity. privateerr.env records it for Gluetun's wrapper and for validated recovery settings.
A representative metadata file contains:
# Generated by Privateerr on 2026-09-23 06:35:34 UTC. Do not edit manually.
PIA_WG_SERVER_NAME=example-server
PIA_WG_ENDPOINT_IP=192.0.2.10
PIA_WG_ENDPOINT_PORT=1337
PIA_REGION_ID=example-region
PIA_REGION_NAME="Example Region"
PIA_PORT_FORWARDING_SUPPORTED=true
PIA_GEOLOCATED_REGION=false
These are documentation values. The UTC timestamp records generation time; reusing a valid saved pair does not change it. An old timestamp alone does not mean a healthy connection needs replacement. Keep both real files private.
Understand readiness and retained files¶
Paths below are relative to the shared WireGuard directory unless shown as absolute paths.
| File or directory | Meaning | Lifetime |
|---|---|---|
wg0.conf and privateerr.env |
Matching saved configuration and metadata | Retained until a verified replacement or explicit regeneration. |
.privateerr-pending/ |
Candidate awaiting API and health confirmation | Retained across uncertain responses and process restarts. |
.privateerr-commit/ |
Copies that let startup finish an interrupted save | Removed after both published files are replaced. |
ready inside either directory |
The copied pair passed validation | Written last and removed with its directory. |
/healthcheck/privateerr.ready |
Startup produced or validated a usable saved pair | Cleared and recreated at startup; does not report live tunnel health. |
Privateerr's Compose healthcheck tests the startup marker. Gluetun's own healthcheck reports the tunnel. Do not delete retained recovery directories while the supervisor runs; the developer architecture describes all temporary files and publication guarantees.
Important variables¶
| Variable | Owner | Meaning |
|---|---|---|
PIA_USER, PIA_PASS |
PIA scripts | Account credentials. |
PIA_AUTOCONNECT |
Compose / PIA scripts | Automatic eligible-region selection. |
PIA_PREFERRED_REGION |
Both Compose examples | Region ID used when automatic selection is off; default ca. |
PIA_PF |
PIA scripts | Request a forwarding-capable region. |
PIA_CONNECT=false |
Privateerr | Generate settings without running the VPN tunnel. |
PIA_CONF_PATH |
PIA scripts | Container output path for wg0.conf. |
PRIVATEERR_METADATA_PATH |
Privateerr | Container output path for privateerr.env. |
PRIVATEERR_KEEPALIVE=true |
Privateerr | Remain running; required for automatic recovery. |
PRIVATEERR_AUTO_RECOVER |
Both services | Enable the supervisor and matching Gluetun wrapper behavior. |
PRIVATEERR_GLUETUN_API_KEY |
Both services | Shared secret for the restricted recovery role. |
VPN_SERVICE_PROVIDER=custom |
Gluetun | Consume the generated WireGuard settings. |
Follow region selection for intentional changes and automatic recovery for timing, authentication, and compatibility. Set routine values in .env; Compose comments explain accepted values and units.
Mount the shared directory¶
Mount the directory containing both outputs, not only wg0.conf. Publication replaces whole files, and pending/commit directories live beside them. Keep it writable by Privateerr's UID 0 and readable by Gluetun. Only one supervisor may own that pair.
Keep Privateerr on the project network, outside Gluetun's VPN namespace, so it can contact PIA while the tunnel is down. The control and health endpoints remain internal to that Docker network; do not publish them for recovery.