Some checks failed
validate / lint (push) Failing after 2s
- Serialize every mutating command (recover, renew, register, rewrite-config, pause, resume, state-reset) on the shared lock, acquired BEFORE state is read rather than after: reading first and locking only around the write let a slower command silently clobber whatever a faster one wrote in between — in particular, an operator pause could be lost to an in-flight recovery pass that read state before the pause ran and only saved its own copy back afterwards. - Fix emergency_close() to reposition its VLAN 50 DROP to the first effective FORWARD position when it exists but has been pushed down by something else (e.g. an out-of-band ufw reload) — a bare `-C` existence check said nothing about position. - Tighten wait_for_verified()'s handshake freshness check from >= to > since_epoch: wg show and since_epoch are both whole seconds, so a handshake at exactly the same second as since_epoch is indistinguishable from a stale, pre-activation one and must not count as proof of a new one. - Fix the Ansible config-validation task to fail on any exit code outside status's three documented health exits (0/1/2), not just on 5 — verified live against the real program (no wg/ip/iptables on this dev machine reproduces the "nothing configured yet" first-run case; status correctly returns 1, and broken/missing config.json correctly returns 5 and is now caught). - Correct the live fault-injection drill in the role README: port 1337 is only the addKey registration API port, not the tunnel's own WireGuard UDP endpoint (derive that from `wg show pia-wg endpoints` instead), and make the packet-capture check direction-aware (`tcpdump -Q out`) so it can't conflate a real egress leak with VLAN 50's normal inbound arrival on enp1s0. Added 6 tests (86 total, all passing): emergency-close repositioning past a preceding ACCEPT, pause/resume blocking on an in-flight lock holder and surviving into a subsequent recovery pass, and the handshake boundary at exactly/one-second-either-side of since_epoch. yamllint, ansible-playbook --syntax-check, and ansible-lint (diffed against main — no new finding categories) all pass. No live changes; nothing pushed to main. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
187 lines
9.4 KiB
YAML
187 lines
9.4 KiB
YAML
---
|
|
# Part of role: pia-gateway
|
|
# Called by: ansible/playbooks/pia-gateway.yaml
|
|
# Description: Default variables for minisforum's PIA WireGuard egress
|
|
# gateway for VPN VLAN 50 — policy routing, kill switch, and health
|
|
# checks. See ~/repo/homelab/plan.md for the cross-repo contract this
|
|
# role implements (fixed values below match that contract).
|
|
|
|
# PIA regions to try, in order, for WireGuard addKey registration —
|
|
# first server (in the first region that has any) to return
|
|
# `status: OK` wins. These are API region **ids** from PIA's serverlist
|
|
# (https://serverlist.piaservers.net/vpninfo/servers/v6), e.g.
|
|
# {"id": "japan", "name": "JP Tokyo", ...} — NOT Gluetun's display names
|
|
# ("JP Tokyo", "Hong Kong", "Taiwan") and not the slug you might guess
|
|
# from one (confirmed live 2026-08-24: Tokyo's id is "japan", not
|
|
# "jp_tokyo" — that matched zero regions on a first pass). Order matches
|
|
# the region set already used by the Gluetun sidecars, Hong Kong/Taiwan
|
|
# moved ahead of Tokyo after all three Tokyo servers were observed
|
|
# failing in practice — see tasks/register.yaml's header for what that
|
|
# means and doesn't mean.
|
|
pia_region_candidates:
|
|
- hk
|
|
- taiwan
|
|
- japan
|
|
|
|
# Force a SINGLE region for troubleshooting, bypassing
|
|
# pia_region_candidates entirely — e.g. `-e pia_region=hk`. This is also
|
|
# an API id, not a display name; same rule as above. Leave null (the
|
|
# default) to use the ordered candidate list. tasks/register.yaml
|
|
# computes the actual list to try (pia_effective_regions) from whichever
|
|
# of these two is set — see that file's own comment for the exact logic,
|
|
# not duplicated here to avoid the two drifting out of sync.
|
|
pia_region: null
|
|
|
|
# WireGuard interface identity. Deliberately not "wg0" — that name is
|
|
# already used by ansible/roles/wireguard, minisforum's separate *inbound*
|
|
# home-VPN server role. Colliding with it would tear down remote access.
|
|
pia_wg_interface: pia-wg
|
|
pia_wg_config_dir: /etc/wireguard
|
|
|
|
# Re-registration behaviour — two independent, unambiguous knobs (an
|
|
# earlier single pia_force_reregister conflated "re-run the API calls"
|
|
# with "get a new keypair", which isn't the same thing and isn't safe to
|
|
# conflate — the key-generation task uses `creates:`, so a naive
|
|
# "force" only re-ran the PIA API calls with the SAME existing key,
|
|
# silently, unless you also knew to delete the key file yourself):
|
|
#
|
|
# - pia_force_reregister: re-run PIA registration (serverlist lookup,
|
|
# token, addKey) even if {{ pia_wg_interface }}.conf already exists.
|
|
# Reuses whatever keypair is already on disk (generates one only if
|
|
# none exists yet). Use this to pick up a new PIA-assigned peer/server
|
|
# without changing minisforum's own WireGuard identity.
|
|
# - pia_force_key_rotation: additionally generate a NEW keypair and
|
|
# register THAT with PIA (implies pia_force_reregister). Rotation is
|
|
# safe-by-construction: the new key is generated to a *.key.new path
|
|
# and only promoted (with the old key backed up alongside a timestamp)
|
|
# after PIA has actually accepted the new key and the new config has
|
|
# been written — see tasks/register.yaml. If registration fails
|
|
# partway, the previous key/config are left completely untouched
|
|
# rather than ending up in a broken half-state.
|
|
pia_force_reregister: false
|
|
pia_force_key_rotation: false
|
|
|
|
# Dedicated policy-routing table for VLAN 50 egress. 0/253/254/255 are
|
|
# kernel-reserved (unspec/default/main/local) — this must stay clear of
|
|
# those and of any other custom table already registered on the host.
|
|
pia_route_table_id: 52
|
|
pia_route_table_name: pia
|
|
|
|
# Rule priority for "from 10.10.50.0/24 lookup pia". Must sort after the
|
|
# kernel's built-in local table (priority 0, always evaluated first, keeps
|
|
# traffic addressed to the host's own local/Technitium address delivered
|
|
# locally per plan.md) and before main (priority 32766).
|
|
pia_rule_priority: 100
|
|
|
|
# Fixed cross-repo contract (see plan.md "Fixed cross-repository
|
|
# contract") — VLAN 50 subnet and the Flint gateway that owns the return
|
|
# route back to VLAN 50. Not derived from live discovery; change only if
|
|
# the contract itself changes.
|
|
pia_vlan50_subnet: 10.10.50.0/24
|
|
pia_flint_gateway: 10.10.50.1
|
|
|
|
# Dedicated iptables chain the kill switch governs, jumped into by a
|
|
# single rule at FORWARD position 1 matching only
|
|
# {{ pia_vlan50_subnet }} — deliberately not a global FORWARD default-
|
|
# policy change, so k3s/Flannel's own FORWARD-chain traffic (source
|
|
# 10.42.0.0/16, disjoint from VLAN 50) is never affected by this role at
|
|
# all. See templates/pia-killswitch.sh.j2 for the full reasoning.
|
|
pia_iptables_chain: PIA-VLAN50
|
|
|
|
# Real parent LAN interface on minisforum — verified live 2026-08-23 via
|
|
# `ip -brief addr`; it is enp1s0, not "eth0". Used for MASQUERADE-exclusion
|
|
# bookkeeping and documentation only, since NAT/forward rules below key off
|
|
# {{ pia_wg_interface }} rather than enumerating the normal interface.
|
|
pia_lan_interface: enp1s0
|
|
|
|
# Reverse-path filtering, applied to {{ pia_wg_interface }} only. The
|
|
# kernel default on minisforum (conf.default.rp_filter) is already loose
|
|
# (2) at time of writing, so new interfaces inherit loose mode — this task
|
|
# pins it explicitly rather than relying on that inherited default holding
|
|
# across future changes. Loose mode is required because PIA's return
|
|
# traffic can legitimately arrive with routing asymmetry relative to how
|
|
# minisforum would route toward that source itself.
|
|
pia_rp_filter_mode: 2
|
|
|
|
# MSS clamping on the pia-wg forward path — ON. Confirmed needed live
|
|
# (2026-08-25), not guessed: a real JDownloader download to
|
|
# sbs237.sbsf.tech hung indefinitely (TLS read timeout waiting for the
|
|
# server's handshake response — small requests like a CDN version check
|
|
# worked fine, only the larger TLS response never arrived). Verified
|
|
# with the exact test plan.md called for before flipping this: `ping -M
|
|
# do -s 1450 -c 3 1.1.1.1` from a VLAN 50 pod returned `From 10.10.40.53
|
|
# Frag needed and DF set (mtu = 1420)` — our own PMTU discovery between
|
|
# the pod and minisforum works correctly, which means the black hole is
|
|
# further out (PIA's network or the remote server's own path), not on
|
|
# our side — exactly the class of problem MSS clamping fixes by
|
|
# avoiding the need for that ICMP round-trip at all, clamping the MSS
|
|
# at the TCP handshake instead of relying on mid-connection PMTU
|
|
# discovery that something further along the path may not relay back.
|
|
pia_mss_clamp_enabled: true
|
|
|
|
# Health check cadence and thresholds. The check only observes and logs —
|
|
# see tasks/healthcheck.yaml — it must never itself open the kill switch.
|
|
pia_healthcheck_interval_sec: 60
|
|
pia_healthcheck_handshake_max_age_sec: 180
|
|
|
|
# ── Automatic recovery (files/pia_gateway.py, tasks/controller.yaml) ────────
|
|
#
|
|
# Which implementation performs PIA registration when this role runs:
|
|
# shared — `pia-gateway register` on the host (the same code the unattended
|
|
# recovery/renewal timers use; activates and VERIFIES a handshake
|
|
# before reporting success).
|
|
# legacy — the original in-Ansible token/addKey flow (tasks/register.yaml).
|
|
# Kept only until the shared path has passed a live manual
|
|
# re-registration; then it is to be deleted (see README).
|
|
pia_registration_backend: shared
|
|
|
|
# Master switch for the reactive recovery timer. false stops+disables the
|
|
# timer but leaves the program, credentials, kill switch, health check and
|
|
# pia-wg in place (controlled rollback). Renewal has its own switch below.
|
|
pia_auto_recovery_enabled: true
|
|
|
|
# Proactive same-key re-registration when the last VERIFIED registration is
|
|
# older than pia_renewal_after_days. Off until the reactive path has passed
|
|
# its live drills (README "Rollout"). Needs a verified baseline in state —
|
|
# established by the shared registration path, never inferred from file
|
|
# mtimes.
|
|
pia_renewal_enabled: false
|
|
pia_renewal_after_days: 21
|
|
pia_renewal_calendar: "*-*-* 03:30:00"
|
|
pia_renewal_jitter_sec: 1800
|
|
|
|
# Recovery state machine tunables (seconds unless noted).
|
|
pia_recovery_failure_threshold: 3
|
|
pia_recovery_startup_grace_sec: 120
|
|
pia_recovery_restart_wait_sec: 90
|
|
pia_recovery_activation_wait_sec: 90
|
|
pia_recovery_max_duration_sec: 600
|
|
pia_recovery_backoff_schedule_sec: [300, 900, 1800, 3600]
|
|
pia_recovery_max_candidates_per_cycle: 6
|
|
pia_recovery_max_rotation_candidates: 3
|
|
pia_recovery_http_connect_timeout_sec: 10
|
|
pia_recovery_http_total_timeout_sec: 30
|
|
pia_recovery_backup_keep: 5
|
|
pia_recovery_lock_wait_sec: 600
|
|
|
|
# Where the on-host controller keeps things.
|
|
pia_gateway_program: /usr/local/sbin/pia-gateway
|
|
pia_gateway_etc_dir: /etc/pia-gateway
|
|
pia_gateway_state_dir: /var/lib/pia-gateway
|
|
|
|
# alert-bridge (manifests/home-services/alert-bridge*.yaml) delivery for
|
|
# state-transition events. Its API has ONE shared bearer key (no per-caller
|
|
# tokens — confirmed against the alert-bridge source), so the same key the
|
|
# cluster uses is provisioned to minisforum's root-only credentials file
|
|
# when pia_alert_bridge_api_key is set (host_vars reads it from .env). Set
|
|
# the URL to null to disable delivery; events still go to the journal.
|
|
pia_alert_bridge_url: "http://alert-bridge.home.arpa/alerts"
|
|
pia_alert_source: "pia-gateway@minisforum"
|
|
pia_alert_bridge_api_key: ""
|
|
|
|
# Deliberate credential removal. Disabling automation never deletes the
|
|
# on-host PIA credentials on its own; set this true (one run) to remove
|
|
# {{ pia_gateway_etc_dir }}/credentials.env, e.g. when decommissioning or
|
|
# after rotating the PIA password elsewhere.
|
|
pia_remove_host_credentials: false
|