Automatic recovery for stale PIA connections - tracking Discussion #66 #129

This records the self-healing request epikaan raised in Discussion #66, the implementation it led to, and the differences from the original setup. Automatic recovery shipped in Privateerr v2.1.0. The feature is implemented and released, and the documentation follow-ups have been reviewed and merged. This retrospective issue keeps the request, work, releases, and setup guidance together.

Original request

Gluetun could keep retrying a stale or unresponsive PIA endpoint without restoring connectivity. The request was for Privateerr to detect the failed tunnel, generate fresh connection settings, and pass them to Gluetun so applications sharing its network could recover.

The supplied Compose setup used deunhealth, staggered healthchecks, and container restarts. It also checked qBittorrent's internet access so it could recover after a Gluetun restart.

What I implemented

Recovery runs inside Privateerr's existing container. After a sustained tunnel failure, it generates and validates fresh PIA settings, applies them through Gluetun's authenticated API, and confirms the applied settings and tunnel health before saving the replacement files.

Gluetun keeps running, so qBittorrent and other attached applications retain their shared network namespace. Recovery includes bounded requests, retry cooldowns, and reconciliation of uncertain API updates. It respects intentional VPN stops and keeps Privateerr's startup readiness independent of tunnel health.

Differences and limits

I chose to address the stale-PIA problem without adding a watchdog container or Docker socket access. The original watchdog also covered container failures; this supervisor cannot restart hung or stopped containers or repair applications orphaned by an external Gluetun replacement.

Recovery can interrupt existing connections. Gluetun still owns the tunnel and forwarded port, and a forwarding-only failure does not rotate an otherwise healthy VPN. Region selection remains respected, so a pinned region does not silently fall back elsewhere.

Restart behavior for existing users

Previously, restarting Privateerr regenerated its configuration and, with automatic selection enabled, reran PIA's latency-based server selection. With recovery enabled, startup reuses a valid saved WireGuard configuration and metadata pair. A healthy connection stays on that server across stack restarts; restarting does not rerun latency selection. Sustained tunnel failures trigger recovery separately.

To intentionally refresh the configuration or rerun automatic server selection, stop the running supervisor and follow the one-shot regeneration procedure, then recreate the VPN stack. Recovery-disabled and one-shot generation retain the previous regeneration behavior.

Implementation and development record

These changes were merged on September 23, 2026. The implementation PR records unit and integration coverage plus live PIA fault-injection tests verifying replacement settings, restored forwarding, and unchanged container identities.

Documentation follow-ups

Privateerr #130 and Plundarrpedia #48 were reviewed and merged on October 10, 2026 after all PR checks passed. They clarify the change from restarting for fresh server selection to reusing a healthy saved connection, and explain how to request explicit regeneration. Privateerr's readiness description now also accounts for saved-file reuse. These changes update the docs without changing runtime behavior.

Source branch links point to the PR head commits so the history stays accessible after branch cleanup. The sidebar milestone records v2.1.0 as the first release of the feature; these later documentation changes are separate follow-ups.

Releases and setup

Privateerr v2.1.0 introduced recovery. Subsequent v2.1 maintenance releases retain it; the current stable release is v2.1.6.

For an existing custom stack, an image update alone does not enable recovery. Adopt the updated Compose/environment settings and Gluetun wrapper, configure the shared API key, and keep Privateerr outside Gluetun's VPN namespace. The wrapper disables Gluetun's competing health-triggered VPN restarts while Privateerr manages recovery.

• Recovery setup, custom deployments, and qBittorrent example
• Comparison with the original watchdog setup
• Plundarrpedia deployment and upgrade guide
• Supervisor architecture

The full development example deliberately interrupts the VPN to test recovery; the guide explains how to run the application services without that test.

@epikaan, thanks again for sharing your setup. It helped shape this feature. When you get a chance, I'd love to hear whether it covers what you needed, or whether anything is still missing. If you'd like a hand adapting your Compose stack, I'm happy to help.