projects/Dockers/gluetun-pia-wireguard-rotator/README.md

gluetun-pia-wireguard-rotator

Sidecar die op een cron-schema (en bij container-start) de snelste PIA WireGuard-region kiest (TCP-latency) via pia-wg-config, wg0.conf op het gedeelde gluetun-volume schrijft, en een configureerbare lijst containers herstart.

Vereisten

• Gluetun met VPN_SERVICE_PROVIDER=custom en VPN_TYPE=wireguard
• Gedeeld volume met gluetun (bijv. /var/dockers/m3u-filter-pia:/gluetun op gluetun, /config op de rotator)
• Docker socket (voor docker restart van gluetun en eventuele sidecar-containers)
• Actief PIA-abonnement

Environment variables

Required

Variable	Description
PIA_USER	PIA-gebruikersnaam
PIA_PASS	PIA-wachtwoord
PIA_REGIONS	CSV (nl_amsterdam,france,belgium) of JSON-array (["nl_amsterdam","france"])

Region-codes moeten overeenkomen met pia-wg-config (niet de OpenVPN-namen uit Gluetun's ingebouwde PIA-provider).

Lijst opvragen:

docker run --rm --entrypoint pia-wg-config bramkel/gluetun-pia-wireguard-rotator:latest --list-regions

Optional

Variable	Default	Description
RESTART_CONTAINERS	—	CSV of JSON-array met extra containers om te herstarten na gluetun (sidecars). Voorbeeld: SabNZBd,qbittorrent,Spotweb
GLUETUN_CONTAINER	m3u-filter-vpn	Gluetun-container; wordt altijd als eerste herstart
WG_CONFIG_PATH	/config/wireguard/wg0.conf	Pad waar wg0.conf wordt geschreven
ROTATOR_STATE_PATH	/config/rotator-state.json	Laatste rotatie-metadata
ROTATE_CRON	0 3 * * *	5-veld cron-expressie (minuut uur dag-van-maand maand dag-van-week), in TZ. Macros: @hourly, @daily, @weekly, @monthly, @yearly
REGION_SELECT	fastest	fastest = laagste TCP-latency naar WG-servers in PIA_REGIONS; random = willekeurig (slaat vorige region over indien mogelijk)
LATENCY_PORT	1337	TCP-poort voor latency-probes
LATENCY_TIMEOUT_SECONDS	2	Timeout per probe
LATENCY_SAMPLES	2	Aantal samples per server-IP (gemiddelde)
LATENCY_SWITCH_MARGIN_MS	15	Alleen switchen van regio als de winst ≥ deze marge is (minder churn / token-calls)
SERVERLIST_CACHE_PATH	/config/cache/pia-serverlist.json	Disk-cache voor PIA serverlist (gedeeld met pia-wg-config)
SERVERLIST_CACHE_TTL	24h	Gebruik cache zonder refresh (Ns/Nm/Nh/Nd of seconden)
SERVERLIST_CACHE_MAX_AGE	168h	Maximale leeftijd; daarna verplicht vernieuwen (stale fallback bij fetch-fout)
WG_CONFIG_MAX_AGE	7d	Geen nieuwe token/config zolang regio gelijk blijft en wg0.conf jonger is
FORCE_ROTATE	false	true = altijd nieuwe config + container-restarts, cache-skip negeren
RATE_LIMIT_WAIT_SECONDS	3600	Wachttijd bij PIA rate-limit (429 / too_many_attempts) vóór retry
TZ	Europe/Brussels	Tijdzone voor scheduling

ROTATE_CRON voorbeelden: 0 */6 * * * (elke 6 uur), 0 3 * * 1-5 (weekdagen 03:00), @hourly. Quote de waarde in Compose ('ROTATE_CRON=0 3 * * *') zodat YAML * niet speciaal interpreteert. Oude ROTATE_AT=HH:MM werkt nog als ROTATE_CRON leeg is.

Output

• wireguard/wg0.conf op het gedeelde volume — Gluetun leest dit als /gluetun/wireguard/wg0.conf en dit overschrijft WIREGUARD_* environment variables
• rotator-state.json — laatste gekozen region, latency-resultaten, timestamp en herstartte containers

Compose-integratie

Zie docker-compose.example.yml voor een volledig voorbeeld met m3u-filter-vpn, m3u-editor en xtream-proxy.

Nieuwe service toevoegen

  gluetun-pia-wireguard-rotator:
    image: bramkel/gluetun-pia-wireguard-rotator:latest
    container_name: gluetun-pia-wireguard-rotator
    restart: unless-stopped
    environment:
      - TZ=Europe/Brussels
      - PIA_USER=${PIA_USER}
      - PIA_PASS=${PIA_PASSWORD}
      - PIA_REGIONS=nl_amsterdam,france,belgium
      - GLUETUN_CONTAINER=downloaders-vpn
      - RESTART_CONTAINERS=SabNZBd,qbittorrent,nzbhydra2,Spotweb
      - 'ROTATE_CRON=0 3 * * *'
      # optioneel: REGION_SELECT=random
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /var/dockers/m3u-filter-pia:/config
    depends_on:
      - m3u-filter-vpn

Zet PIA_USER en PIA_PASSWORD in een host-.env (niet inline in compose).

Gluetun opschonen (aanbevolen na eerste succesvolle rotatie)

Zodra wg0.conf bestaat, heeft het bestand voorrang op env-vars. Verwijder uit m3u-filter-vpn om verwarring te voorkomen:

• WIREGUARD_ENDPOINT_IP
• WIREGUARD_PUBLIC_KEY
• WIREGUARD_PRIVATE_KEY
• WIREGUARD_ADDRESSES

Behoud minimaal:

    environment:
      - VPN_SERVICE_PROVIDER=custom
      - VPN_TYPE=wireguard

Optioneel host-.env-keys (WIREGUARD_*) opruimen als die niet meer gebruikt worden.

Deploy

1. Push/build image (Dockers/gluetun-pia-wireguard-rotator/** triggert Gitea CI → bramkel/gluetun-pia-wireguard-rotator:latest)
2. docker compose up -d gluetun-pia-wireguard-rotator
3. Controleer logs: docker logs gluetun-pia-wireguard-rotator en docker logs m3u-filter-vpn

Gedrag

1. Bij start / cron: latency meten (of random kiezen)
2. Serverlist komt uit disk-cache (SERVERLIST_CACHE_*); token/API alleen bij echte config-refresh
3. Geen pia-wg-config + geen restarts als regio gelijk blijft én wg0.conf jonger is dan WG_CONFIG_MAX_AGE
4. Anders: nieuwe config schrijven, GLUETUN_CONTAINER eerst herstarten, daarna RESTART_CONTAINERS

Let op: zet gluetun niet in RESTART_CONTAINERS; gebruik GLUETUN_CONTAINER daarvoor. Sidecars met network_mode: service:... horen in RESTART_CONTAINERS.

Let op: elke rotatie veroorzaakt kort downtime voor alle VPN-afhankelijke services.

Security

• De Docker socket geeft de rotator rechten om containers te herstarten; mount read-only waar mogelijk
• wg0.conf bevat private keys (chmod 600)
• Bewaar PIA-credentials in .env, niet in version control