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 these 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 the one-shot generation 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 recreate 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, Privateerr registers fresh PIA WireGuard settings and applies them 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 bundled wrapper 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. A selected region stays pinned during recovery. See Privateerr's recovery guide for the full sequence, authentication routes, and limits.

Update an existing deployment

Use a Privateerr release that includes automatic Gluetun recovery before applying these settings. A saved PRIVATEERR_TAG pin remains unchanged during regeneration. Pull the updated Maraudarr generator and regenerate your selected preset:

make pull-image
make ship PRESET=YOUR-PRESET

Regeneration adds missing recovery settings and generates the shared key. It upgrades the unchanged previous bundled Gluetun wrapper, while preserving WireGuard state, application data, existing keys, and an explicit recovery opt-out.

Important

Customized, symlinked, or older unrecognized wrappers remain untouched. Before recreating such a deployment, update the script selected by GLUETUN_WRAPPER_SCRIPT_PATH using the current wrapper, or set PRIVATEERR_AUTO_RECOVER=false. If you maintain /gluetun/auth/config.toml yourself, add Privateerr's recovery role with the same shared key; the wrapper preserves that file.

Then recreate the complete stack with make up PRESET=YOUR-PRESET. In Synology Container Manager, rebuild the project using its regenerated Compose file and updated .env. Check Privateerr's logs for automatic recovery being enabled and Gluetun's logs for the tunnel becoming healthy. 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 own network namespace before startup. Keep PIA_DISABLE_IPV6=yes; the updated Privateerr wrapper recognizes the existing IPv6 settings and avoids redundant sysctl writes without hiding warnings. Regeneration preserves an existing PIA setting and adds the namespace setting. Keep Privateerr's mounted configuration directories writable by UID 0.

Use a Privateerr release containing both recovery and the IPv6 wrapper update before recreating a generated deployment. An image-only Watchtower update retains existing container options, so older deployments remain privileged until their Compose configuration is updated and the container is recreated. Missing recovery settings continue to 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.