Nik Afiq 87a9303cc3
Some checks failed
validate / lint (push) Failing after 2s
fix: address code review on pia-gateway auto-recovery controller
- 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>
2026-09-22 15:51:02 +09:00

163 lines
6.3 KiB
YAML

---
# Part of role: pia-gateway
# Called by: ansible/playbooks/pia-gateway.yaml
# Description: Orchestrates minisforum's PIA WireGuard egress gateway for
# VPN VLAN 50 — kill switch + policy routing, the on-host recovery
# controller, registration, the WireGuard interface itself, and health
# checks. Split into included files because each stage has a distinct
# idempotency/ordering concern; see the comment at the top of each.
#
# Ordering (changed with the auto-recovery work, deliberately):
# 1. tooling, baseline assertions
# 2. controller program + config + credentials (NOT its timers)
# 3. quiesce the recovery/renewal timers for the rest of the run so a
# timer-driven restart can never race an Ansible handler restart
# 4. kill switch + routing + firewall, handlers flushed so the closed
# state is live BEFORE anything can activate a tunnel
# 5. registration (shared backend activates + verifies under the lock;
# the legacy backend only writes the config and notifies a restart)
# 6. interface unit enabled, health check installed, handlers flushed
# 7. timers enabled/disabled per pia_auto_recovery_enabled /
# pia_renewal_enabled
- name: Install WireGuard tooling and iproute2
ansible.builtin.apt:
name:
- wireguard
- wireguard-tools
- iproute2
- python3
state: present
update_cache: true
# python3-requests is no longer needed: the controller uses only the
# standard library.
- name: Pin reverse-path filtering for {{ pia_wg_interface }}
ansible.posix.sysctl:
name: "net.ipv4.conf.{{ pia_wg_interface }}.rp_filter"
value: "{{ pia_rp_filter_mode | string }}"
sysctl_file: /etc/sysctl.d/60-pia-gateway.conf
reload: false # interface does not exist yet on a first run; applied for real after the WG interface comes up
register: pia_rp_filter_pinned
- name: Confirm host default route and ip_forward are untouched
ansible.builtin.include_tasks: assert-baseline.yaml
- name: Install the recovery controller, its config and credentials
ansible.builtin.include_tasks: controller.yaml
- name: Check whether the recovery timer is installed from a previous run
ansible.builtin.stat:
path: /etc/systemd/system/pia-gateway-recover.timer
register: pia_recover_timer_stat
- name: Quiesce the recovery and renewal timers for the duration of this run
ansible.builtin.systemd:
name: "{{ item }}"
state: stopped
loop:
- pia-gateway-recover.timer
- pia-gateway-renew.timer
when: pia_recover_timer_stat.stat.exists
failed_when: false
# failed_when: false — on the very first install the units were just
# deployed and never started; "stopping" them is a harmless no-op that
# some systemd versions report as an error for never-loaded timers.
- name: Wait for any in-flight recovery/renewal pass to finish
ansible.builtin.command:
cmd: systemctl is-active pia-gateway-recover.service pia-gateway-renew.service
register: pia_inflight
changed_when: false
failed_when: false
until: "'active' not in (pia_inflight.stdout_lines | default([]) | map('trim') | list)"
retries: 90
delay: 10
when: pia_recover_timer_stat.stat.exists
# A pass can take up to pia_recovery_max_duration_sec (+ restart waits);
# we never kill it mid-activation. Registration below also takes the
# program's own lock, so this is belt-and-braces for the handler restarts.
- name: Configure boot-ordered kill switch and policy routing
ansible.builtin.include_tasks: routing.yaml
- name: Configure firewall-layer kill switch and Technitium access
ansible.builtin.include_tasks: firewall.yaml
- name: Apply kill-switch handlers before anything can activate a tunnel
ansible.builtin.meta: flush_handlers
- name: Register minisforum with PIA (shared on-host transaction)
ansible.builtin.include_tasks: register-shared.yaml
when: pia_registration_backend == "shared"
- name: Register minisforum with PIA (legacy in-Ansible flow)
ansible.builtin.include_tasks: register-legacy.yaml
no_log: true # PIA credentials and the derived private key pass through this include
when: pia_registration_backend == "legacy"
- name: Write and enable the pia-wg WireGuard interface
ansible.builtin.include_tasks: interface.yaml
- name: Install gateway health checks
ansible.builtin.include_tasks: healthcheck.yaml
- name: Re-apply rp_filter now that {{ pia_wg_interface }} exists
ansible.posix.sysctl:
name: "net.ipv4.conf.{{ pia_wg_interface }}.rp_filter"
value: "{{ pia_rp_filter_mode | string }}"
sysctl_file: /etc/sysctl.d/60-pia-gateway.conf
reload: true
when: pia_rp_filter_pinned is succeeded
- name: Apply remaining handlers while the timers are still quiesced
ansible.builtin.meta: flush_handlers
- name: Re-render pia-wg.conf when only the controller config changed (no PIA call)
ansible.builtin.command:
cmd: "{{ pia_gateway_program }} rewrite-config"
register: pia_rewrite_result
changed_when: pia_rewrite_result.rc == 0
failed_when: pia_rewrite_result.rc not in [0, 5]
when:
- pia_registration_backend == "shared"
- pia_gateway_config_result is changed
- not (pia_registered_this_run | default(false) | bool)
# Picks up hook-content changes (e.g. pia_mss_clamp_enabled) without a
# forced re-registration — the gap noted in the 2026-08-25 incident.
# Exit 5 = "no verified registration recorded yet" (legacy-registered
# host); that is not an error here, the next registration will render
# the current hooks.
- name: Enable the recovery timer
ansible.builtin.systemd:
name: pia-gateway-recover.timer
enabled: true
state: started
daemon_reload: true
when: pia_auto_recovery_enabled | bool
- name: Disable the recovery timer (pia_auto_recovery_enabled=false)
ansible.builtin.systemd:
name: pia-gateway-recover.timer
enabled: false
state: stopped
daemon_reload: true
when: not (pia_auto_recovery_enabled | bool)
- name: Enable the renewal timer
ansible.builtin.systemd:
name: pia-gateway-renew.timer
enabled: true
state: started
daemon_reload: true
when: (pia_auto_recovery_enabled | bool) and (pia_renewal_enabled | bool)
- name: Disable the renewal timer
ansible.builtin.systemd:
name: pia-gateway-renew.timer
enabled: false
state: stopped
daemon_reload: true
when: not ((pia_auto_recovery_enabled | bool) and (pia_renewal_enabled | bool))