Configure VPN regions and recovery 🧶
Choose a VPN region¶
Deployments containing Privateerr include these controls in the generated .env:
| Setting | Default | Behavior |
|---|---|---|
PIA_AUTOCONNECT |
true |
Select the lowest-latency eligible region; false uses the preferred region. |
PIA_PREFERRED_REGION |
ca |
PIA region ID to use when automatic selection is disabled. |
PIA_PF |
true |
Filter automatic selection to regions that advertise port forwarding. |
To select Montreal, change PIA_AUTOCONNECT to false. To choose another region, also edit PIA_PREFERRED_REGION; Canadian alternatives include ca_toronto (Toronto), ca_vancouver, and ca_ontario. Set PIA_AUTOCONNECT back to true to resume automatic selection; the saved preferred region is ignored until you disable it again. Dedicated-IP deployments use PIA_DIP_TOKEN instead of region selection.
Recovery-enabled startup reuses valid saved files. Recreating containers loads the changed environment but does not immediately replace a healthy connection. To apply an intentional region or forwarding-selection change, stop the selected stack, generate a fresh pair with recovery and keepalive disabled for that one run, then recreate the complete stack. Replace YOUR-PRESET with the generated preset name:
docker compose --project-directory dist/YOUR-PRESET stop
docker compose --project-directory dist/YOUR-PRESET run --rm --no-deps -e PRIVATEERR_AUTO_RECOVER=false -e PRIVATEERR_KEEPALIVE=false privateerr
make up PRESET=YOUR-PRESET
Run Make commands from the Plundarr repository root. For a deployment managed directly with Compose, run docker compose stop, the same docker compose run command without --project-directory, and docker compose up --detach --force-recreate from its generated project directory. Stopping the supervisor prevents concurrent writers; recreating the full stack keeps Gluetun and its network-sharing applications together.
In Synology Container Manager, stop the project before generating the new PIA WireGuard configuration file and rebuild it afterward using the updated .env. If you manage this entirely through the UI, temporarily set PRIVATEERR_AUTO_RECOVER=false, rebuild and verify fresh generation, then restore true and rebuild again. A container restart alone does not reload environment changes. Keep the generated Compose mappings in place.
Check Privateerr's logs for the selected region and Gluetun's logs for successful port forwarding. PIA's advertised forwarding support does not guarantee its forwarding API is currently available. If a region's API fails, choose another forwarding-capable region in .env and generate the new PIA WireGuard configuration file using the procedure above before recreating the project. No manual Compose edits are needed. Steer around the storm, captain.
Recover stale connections automatically 🛟¶
Generated deployments enable PRIVATEERR_AUTO_RECOVER=true whenever the resolved selection includes both Privateerr and Gluetun. This includes the Plundarr and Boudoirr core services, custom VPN selections, and download clients that add both services as dependencies. Privateerr on its own keeps recovery disabled; presets without Privateerr gain no recovery settings.
Maraudarr generates one random PRIVATEERR_GLUETUN_API_KEY in the deployment's private .env and supplies it to both containers. Regeneration preserves that key and your timing settings. The generated example.env leaves the key empty and contains no deployment credentials.
After a sustained tunnel outage, the Python supervisor inside the Privateerr container registers a new PIA WireGuard configuration and applies it through Gluetun's authenticated control API. Gluetun restarts its internal tunnel while its container and shared network namespace stay in place. Privateerr saves the replacement files only after the settings match and the tunnel is healthy. No extra service or Docker socket is required.
The wrapper installed by Privateerr lets Privateerr reach Gluetun's health listener over the shared Docker network and creates a temporary authentication role with only the recovery routes. Neither the health port nor the control API is published to the host. While recovery is enabled, the wrapper disables Gluetun's competing health-triggered restarts. Gluetun still owns the tunnel, firewall, and port forwarding, including qBittorrent's port-update hooks.
| Setting | Default | Purpose |
|---|---|---|
PRIVATEERR_AUTO_RECOVER |
true with both services |
Enable the recovery monitor. |
PRIVATEERR_RECOVERY_INTERVAL_SECONDS |
30 |
Seconds between health probes. |
PRIVATEERR_RECOVERY_FAILURE_SECONDS |
120 |
Startup grace and continuous failure threshold, in seconds. |
PRIVATEERR_RECOVERY_COOLDOWN_SECONDS |
300 |
Initial retry delay in seconds; failed attempts back off up to one hour. |
PRIVATEERR_GENERATION_TIMEOUT_SECONDS |
180 |
Maximum seconds for each PIA configuration generation. |
To disable recovery, set PRIVATEERR_AUTO_RECOVER=false in the generated .env and recreate the complete stack with make up PRESET=YOUR-PRESET. The wrapper then uses your normal GLUETUN_HEALTH_RESTART_VPN setting. A manually stopped VPN pauses automatic recovery; an unreachable or unauthorized control API does not trigger repeated PIA registrations. A port-forwarding-only failure does not rotate a healthy tunnel.
Recovery respects PIA_AUTOCONNECT, PIA_PREFERRED_REGION, and PIA_PF. With PIA_AUTOCONNECT=false, recovery stays within your selected region. With automatic selection enabled, recovery tries eligible endpoints in the current region before other regions. See Privateerr's recovery guide for the full sequence, authentication routes, and limits.
Configure the recovery wrapper¶
Privateerr installs its packaged startup wrapper and qBittorrent forwarding hook into /gluetun/scripts on every startup before reporting healthy. Gluetun runs GLUETUN_ENTRYPOINT_WRAPPER=/gluetun/scripts/gluetun-entrypoint-wrapper.sh through the existing configuration mount. No external script download or individual script mount is required.
Privateerr owns gluetun-entrypoint-wrapper.sh and qbittorrent-port-forwarding.sh in that directory and replaces them from the selected image. Keep operator scripts under separate names. GLUETUN_ENTRYPOINT_WRAPPER must name an existing file inside Gluetun; the generated chart mounts the shared configuration directory and does not install custom wrappers. Maraudarr preserves explicitly saved path values. A custom wrapper must implement the configured health listener and authenticated control role. Maraudarr preserves WireGuard state, application data, existing keys, and explicit recovery choices. An operator-managed /gluetun/auth/config.toml must provide Privateerr's recovery role with the shared key; the wrapper preserves that file. Set PRIVATEERR_AUTO_RECOVER=false when the selected wrapper or authentication configuration does not support recovery. Keep the API key and VPN configuration out of support reports.
Run Privateerr without privileged mode¶
Generated Privateerr services drop all Linux capabilities and enable no-new-privileges. The unmodified PIA scripts still run as UID 0, but Privateerr does not receive VPN device or network-administration privileges. Gluetun retains the privileges required to run its tunnel.
The generated .env sets PRIVATEERR_IPV6_DISABLED=1, which Docker applies to Privateerr's network namespace before startup. Keep PIA_DISABLE_IPV6=yes; Privateerr honors those settings without redundant sysctl writes. Its mounted configuration directories must remain writable by UID 0.
Privateerr runs its Python supervisor directly, invokes the unmodified PIA scripts, and reports readiness after integration scripts and valid VPN files exist. Its health status describes startup readiness; it does not certify current tunnel health or future recovery writes. Review operation-specific storage and API diagnostics in its logs. Missing recovery settings mean recovery is disabled. The bundled VPN services disable unattended Watchtower updates through their container labels.
Coordinate qBittorrent maintenance¶
Every generated deployment containing qBittorrent uses depends_on.gluetun.restart: true. An explicit Compose restart or update of Gluetun also restarts qBittorrent so the application follows planned VPN-container maintenance. This setting does not react to health failures, Docker's automatic restart policy, or Watchtower replacements. Privateerr's API recovery keeps both containers running and does not trigger this dependency restart. Recreate the complete stack when changing the network namespace outside Compose.
The QBITTORRENT_WEBUI_PORT value controls the host port, internal Web UI listener, healthcheck, and default forwarding-hook API address together, including presets using a different port. Gluetun receives QBITTORRENT_PORT_SYNC=true and a bounded QBITTORRENT_API_WAIT_SECONDS=300 wait. Privateerr supplies the hook; it binds the application to the assigned peer port and VPN interface without publishing peer ports on the host.
The seeded qBittorrent API allows unauthenticated access from loopback in the shared VPN namespace. Remote Web UI clients still authenticate. Other containers sharing that namespace also share its loopback trust boundary. An existing qBittorrent configuration must permit the local hook to use its API.