# gluetun-pia-wireguard-rotator

Sidecar die de **snelste** PIA WireGuard-server kiest (TCP-latency), lokaal een keypair maakt, via PIA `addKey` registreert, `wg0.conf` schrijft, en Gluetun (+ sidecars) herstart. Pollt Gluetun-health elke 10s en herstelt bij `unhealthy`.

## Vereisten

- Gluetun met `VPN_SERVICE_PROVIDER=custom` en `VPN_TYPE=wireguard`
- Docker **healthcheck** op de Gluetun-container (anders werkt alleen cron)
- Gedeeld volume met gluetun (bijv. `/var/dockers/m3u-filter-pia:/gluetun` ↔ `/config`)
- Docker socket (voor `docker restart` / health inspect)
- 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 |

Region-IDs komen uit de PIA serverlist.

```bash
docker run --rm --entrypoint /opt/venv/bin/python \
  bramkel/gluetun-pia-wireguard-rotator:latest \
  /usr/local/bin/rotate.py --list-regions
```

### Optional

| Variable | Default | Description |
|----------|---------|-------------|
| `RESTART_CONTAINERS` | — | Extra containers na gluetun (sidecars) |
| `GLUETUN_CONTAINER` | `m3u-filter-vpn` | Gluetun-container (eerste restart + health poll) |
| `WG_CONFIG_PATH` | `/config/wireguard/wg0.conf` | Pad voor `wg0.conf` |
| `ROTATOR_STATE_PATH` | `/config/rotator-state.json` | Rotatie-metadata |
| `ROTATE_CRON` | `0 3 * * *` | Periodieke latency-check (soft) |
| `HEALTH_CHECK_INTERVAL` | `10` | Seconden tussen health/cron polls |
| `UNHEALTHY_ROTATE_COOLDOWN` | `60` | Wachttijd na unhealthy-rotatie om healthy te worden |
| `REGION_SELECT` | `fastest` | `fastest` of `random` |
| `LATENCY_PORT` | `1337` | TCP-poort voor latency-probes |
| `LATENCY_TIMEOUT_SECONDS` | `2` | Timeout per probe |
| `LATENCY_SAMPLES` | `2` | Samples per IP |
| `LATENCY_SWITCH_MARGIN_MS` | `15` | Soft stickiness bij cron (niet bij unhealthy force) |
| `SERVERLIST_CACHE_PATH` | `/config/cache/pia-serverlist.json` | Serverlist-cache |
| `SERVERLIST_CACHE_TTL` | `24h` | Cache-TTL |
| `SERVERLIST_CACHE_MAX_AGE` | `168h` | Max stale age |
| `TOKEN_CACHE_PATH` | `/config/cache/pia-token.json` | Token-cache |
| `TOKEN_CACHE_TTL` | `20h` | Token hergebruik |
| `PIA_CA_PATH` | `/config/cache/ca.rsa.4096.crt` | PIA CA voor addKey |
| `FORCE_TOKEN_REFRESH` | `false` | Token-cache negeren |
| `RATE_LIMIT_WAIT_SECONDS` | `3600` | Cooldown bij PIA rate-limit |
| `RATE_LIMIT_PATH` | `/config/cache/pia-rate-limit.json` | Persistente rate-limit cooldown |
| `TZ` | `Europe/Brussels` | Tijdzone |

## Compose

```yaml
  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 */6 * * *'
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /var/dockers/m3u-filter-pia:/config
    depends_on:
      - m3u-filter-vpn
```

## Gedrag

1. **Startup:** force-rotatie (beste server + nieuwe keypair)
2. **Elke `HEALTH_CHECK_INTERVAL`:** health van `GLUETUN_CONTAINER` checken
3. **Unhealthy recovery (max 2 stappen):**
   - Stap 1: force beste server + nieuwe keypair (keypair kan invalid zijn)
   - Wacht tot `UNHEALTHY_ROTATE_COOLDOWN` of tot healthy
   - Nog unhealthy → stap 2: exclude die IP, force runner-up (#2 latency)
4. **Cron due:** latency opnieuw meten; **zelfde beste server** → geen token/addKey/restarts
5. Rate-limit: persistente cooldown, daarna retry

**Let op:** zet gluetun niet in `RESTART_CONTAINERS`. Elke echte rotatie geeft korte downtime.