From b8f25e9d80c96f7170d51eb5abcd662a66d55317 Mon Sep 17 00:00:00 2001
From: Ahmed Abdelhalim <pm@a14m.dev>
Date: Wed, 8 Jul 2026 14:28:33 +0200
Subject: Route IPv6 through WireGuard VPN via radvd and static gateway
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add radvd to gateway role to advertise Pi as high-preference IPv6
default router using the stable ULA prefix (fd1e:.../64). With
FritzBox also sending RAs, devices end up with ECMP between Pi and
FritzBox. To solve this, add network_ipv6_gateway (Pi's link-local)
as a static route with metric 100 to all managed hosts — beats RA
metric 425, ensuring all IPv6 default traffic goes through Pi.

Fix IPv6 MASQUERADE in gateway-apply-rules:
- Direct mode: add MASQUERADE on end0 (LAN devices use ULA source
  addresses not known to FritzBox, so Pi must NAT them)
- FORWARD rules: restrict to RELATED,ESTABLISHED only — previously
  the broad ACCEPT rule passed un-NAT'd packets alongside masqueraded
  copies, causing duplicate SYNs, conntrack corruption, and RSTs
- MASQUERADE/clear rules: match by interface not by source subnet
  (devices may use any source address, not just the ULA prefix)
- VPN mode return traffic: explicitly restrict to wg+→end0 direction

Add network_ipv6_gateway var (optional) to network role NM templates
(ethernet, wifi, bridge) — injects a static IPv6 default route at
metric 100 when set. Add rpi5 static route to FritzBox link-local so
Pi keeps IPv6 after FritzBox RA is disabled.

Force SSH to IPv4 for *.local hosts (AddressFamily inet) — prevents
Ansible from hanging on mDNS returning multiple IPv6 addresses.

Update gateway and pihole READMEs with two-step IPv6 setup process.

Co-Authored-By: Claude.ai
---
 roles/pihole/README.md | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

(limited to 'roles/pihole')

diff --git a/roles/pihole/README.md b/roles/pihole/README.md
index c690dffb..e7e0bb20 100644
--- a/roles/pihole/README.md
+++ b/roles/pihole/README.md
@@ -47,11 +47,10 @@ This role configure the [pihole](https://github.com/pi-hole/pi-hole) DNS Sinkhol
 
 #### With IPv6 Support
 
-> **Note:** IPv6 support is currently disabled due to ISP compatibility issues. The steps below are kept
-> for future reference. IPv6 on the network template defaults to `method=disabled`.
-> To enable: set `method=auto` in `roles/network/templates/eth0-connection.nmconnection.j2` and follow
-> the steps below to obtain a stable ULA address via SLAAC.
-> Use the `mngtmpaddr` address from `ip address | grep "inet6 fd"` as `{{ pihole_ipv6 }}` — not the `temporary` one.
+Setup is a two-step process: first enable FritzBox RA to get the Pi's stable ULA address,
+then disable FritzBox RA so Pi becomes the sole IPv6 default router.
+
+**Step 1 — Enable FritzBox RA temporarily to get Pi's ULA address:**
 
 - Internet > Account Information >
   - IPv6 > IPv6 Support > ✅
@@ -70,4 +69,22 @@ This role configure the [pihole](https://github.com/pi-hole/pi-hole) DNS Sinkhol
   - DHCPv6 Server in the home network >
     - Disable DHCPv6 server in the FRITZ!Box for the home network > ✅
       - There are no other DHCPv6 servers in the home network. > ✅
+
 - Internet > Account Information > Internet DNS Server > DNSv6 Server > Use Other DNSv6 Servers > {{ pihole_ipv6 }}
+
+On the Pi, get the ULA address and the FritzBox link-local default route:
+```bash
+ip address | grep "inet6 fd"         # use the mngtmpaddr address as pihole_ipv6
+ip -6 route show default | grep ra   # use the nexthop as network_ipv6_gateway in rpi5 host_vars
+```
+
+Set `network_ipv6_gateway` in `host_vars/rpi5.local.yml` and run the playbook to deploy the static IPv6 route on Pi.
+
+**Step 2 — Disable FritzBox RA so Pi becomes sole IPv6 default router:**
+
+- Home Network > Network > Network Settings > Change Advanced Network Settings > IPv6 >
+  - Router advertisement enable in the LAN > ❌
+
+NOTE: Pi's radvd (deployed by the `gateway` role) takes over sending RAs with `AdvDefaultPreference high`.
+All LAN devices use Pi as their IPv6 default router → traffic routes VPN or direct mode.
+Pi keeps IPv6 connectivity via the static route to FritzBox set in Step 1.
-- 
cgit v1.2.3