Re-resolve WireGuard peers' endpoint names

systemd-networkd resolves an endpoint name once, when it creates the
device. A peer behind a dynamic DNS name that changes its address was
never found again until the next restart.

A timer (router.wireguardEndpointRefresh, default 1min, null for off)
runs wg set for the peers with a name whose last handshake is older than
135 seconds, as wireguard-tools' reresolve-dns does. Working tunnels are
left alone.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AeFqV9dZrK6nipHkPfyM4F

SPECS.md

@@ -181,6 +181,7 @@ Needed to replace the user's hand-written router (host `antigua`, dnsmasq). Serv
 - **Kill switch** (default on): forwarded packets for a tunnel's `allowedIPs` are dropped if they would leave via an uplink (placed before the established-accept, so flows that were in the tunnel are cut too).
 - **Addresses** are explicit (`addresses` list, empty for site-to-site); nothing generated. No IPv6 internet for road warriors (the delegated /64 belongs to a LAN; NPTv6 not implemented).
 - **Keys**: `privateKeyFile` (and `presharedKeyFile`) outside the Nix store, handed to the unprivileged systemd-networkd via `LoadCredential`, so files can stay root-only 0600. Deployment must provide them.
+- **Endpoint names**: networkd resolves a hostname in a peer's `endpoint` when it creates the device and retries (0.2 s doubling to 25.6 s) until it resolves, so boot order is fine (seen on the real router: four failures, then success once PPPoE was up). It never resolves again, so a peer's new address (dynamic DNS) is not noticed. `router.wireguardEndpointRefresh` (default `1min`, null = off) runs `router-wireguard-reresolve` (a timer), which sets the endpoint again with `wg set` for named peers that have no handshake in the last 135 s (a working tunnel is not touched). Tested in `wireguard` (a peer that never answers, a changing /etc/hosts, a working tunnel left alone).
 
 ## Replacing `antigua` (the user's hand-written router)
 

modules/router/options.nix

@@ -426,6 +426,20 @@ in
       );
     };
 
+    wireguardEndpointRefresh = mkOption {
+      type = types.nullOr (types.strMatching "[0-9]+(s|min|h)");
+      default = "1min";
+      example = "5min";
+      description = ''
+        How often the names in WireGuard peers' `endpoint` are looked up
+        again, for peers that have not completed a handshake in the last two
+        minutes. systemd-networkd resolves a name only when it creates the
+        tunnel, so without this a tunnel whose peer got a new address (dynamic
+        DNS) stays down until the peer contacts the router, or forever if both
+        ends changed. A tunnel that works is not touched. null turns it off.
+      '';
+    };
+
     firewall.zones = mkOption {
       type = types.listOf types.str;
       default = [ ];

modules/router/wireguard.nix

@@ -1,4 +1,9 @@
-{ config, lib, ... }:
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
 let
   cfg = config.router;
 
@@ -20,6 +25,27 @@ let
       )
     ) cfg.wireguard
   );
+
+  # Peers whose endpoint is a name (not an address). systemd-networkd looks a
+  # name up when it creates the device (and retries until it resolves, every
+  # 25 s at most), but never again: after the peer's address changes both
+  # sides keep sending to the old one.
+  isName = e: e != null && !lib.hasPrefix "[" e && builtins.match "[0-9.]+:[0-9]+" e == null;
+  namedPeers = lib.concatLists (
+    lib.mapAttrsToList (
+      name: wg:
+      lib.concatLists (
+        lib.mapAttrsToList (
+          peer: p:
+          lib.optional (isName p.endpoint) {
+            inherit (wg) interface;
+            inherit peer;
+            inherit (p) publicKey endpoint;
+          }
+        ) wg.peers
+      )
+    ) cfg.wireguard
+  );
 in
 {
   config = lib.mkIf (cfg.enable && cfg.wireguard != { }) {
@@ -79,5 +105,70 @@ in
         ) (lib.attrValues wg.peers);
       }
     ) cfg.wireguard;
+    # Look the names up again, like wireguard-tools' reresolve-dns: only for
+    # peers that have not shown a handshake lately (a working tunnel is left
+    # alone; with keepalive, handshakes are at most about two minutes apart).
+    systemd.services.router-wireguard-reresolve =
+      lib.mkIf (cfg.wireguardEndpointRefresh != null && namedPeers != [ ])
+        {
+          description = "Look up the names of WireGuard peer endpoints again";
+          after = [ "systemd-networkd.service" ];
+          path = [
+            pkgs.wireguard-tools
+            pkgs.gawk
+            pkgs.coreutils
+          ];
+          script = ''
+            now=$(date +%s)
+            refresh() { # device peer-name public-key endpoint
+              last=$(wg show "$1" latest-handshakes 2>/dev/null | awk -v k="$3" '$1 == k { print $2 }')
+              [ -n "$last" ] || return 0 # no such device or peer (yet)
+              if [ "$last" -gt 0 ] && [ $((now - last)) -lt 135 ]; then return 0; fi
+              before=$(wg show "$1" endpoints | awk -v k="$3" '$1 == k { print $2 }')
+              if ! wg set "$1" peer "$3" endpoint "$4"; then
+                echo "$1: $2: cannot resolve $4"
+                return 0
+              fi
+              after=$(wg show "$1" endpoints | awk -v k="$3" '$1 == k { print $2 }')
+              if [ "$before" != "$after" ]; then echo "$1: $2: endpoint $before -> $after ($4)"; fi
+            }
+          ''
+          + lib.concatMapStrings (
+            p:
+            "refresh ${
+              lib.escapeShellArgs [
+                p.interface
+                p.peer
+                p.publicKey
+                p.endpoint
+              ]
+            }\n"
+          ) namedPeers;
+          serviceConfig = {
+            Type = "oneshot";
+            CapabilityBoundingSet = [ "CAP_NET_ADMIN" ];
+            RestrictAddressFamilies = [
+              "AF_INET"
+              "AF_INET6"
+              "AF_NETLINK"
+              "AF_UNIX"
+            ];
+            NoNewPrivileges = true;
+            PrivateTmp = true;
+            PrivateDevices = true;
+            ProtectSystem = "strict";
+            ProtectHome = true;
+          };
+        };
+    systemd.timers.router-wireguard-reresolve =
+      lib.mkIf (cfg.wireguardEndpointRefresh != null && namedPeers != [ ])
+        {
+          wantedBy = [ "timers.target" ];
+          timerConfig = {
+            OnBootSec = "2min";
+            OnUnitActiveSec = cfg.wireguardEndpointRefresh;
+            AccuracySec = "10s";
+          };
+        };
   };
 }

tests/wireguard.nix

@@ -168,6 +168,12 @@ pkgs.testers.runNixOSTest {
         networking.interfaces.eth1.ipv4.addresses = lib.mkForce [ ];
         networking.interfaces.eth2.ipv4.addresses = lib.mkForce [ ];
 
+        # Names for peer endpoints, so the test can move them.
+        networking.hosts = {
+          "203.0.113.60" = [ "siteb.test" ];
+          "203.0.113.70" = [ "ghost.test" ];
+        };
+
         environment.etc = lib.listToAttrs (
           map
             (n: {
@@ -182,7 +188,14 @@ pkgs.testers.runNixOSTest {
               "s2s"
               "ff"
             ]
-        );
+        )
+        // {
+          # A tunnel to a peer that does not exist: it never has a handshake.
+          "wg/ghost.key" = {
+            text = key.router-rw.priv;
+            mode = "0600";
+          };
+        };
 
         router = {
           enable = true;
@@ -230,11 +243,20 @@ pkgs.testers.runNixOSTest {
               sourceAddresses = [ "192.168.10.1" ];
               peers.siteb = {
                 publicKey = key.siteb.pub;
-                endpoint = "203.0.113.60:51821";
+                endpoint = "siteb.test:51821";
                 allowedIPs = [ "192.168.50.0/24" ];
                 persistentKeepalive = 5;
               };
             };
+            ghost = {
+              privateKeyFile = "/etc/wg/ghost.key";
+              zone = "ghost";
+              peers.nobody = {
+                publicKey = key.laptop.pub;
+                endpoint = "ghost.test:51830";
+                allowedIPs = [ "192.168.77.0/24" ];
+              };
+            };
             # Provider tunnel: only the listed destinations go through it.
             ff = {
               privateKeyFile = "/etc/wg/ff.key";
@@ -362,6 +384,23 @@ pkgs.testers.runNixOSTest {
         for dev in ("wg-rw", "wg-s2s", "wg-ff"):
             router.wait_until_succeeds(f"wg show {dev} latest-handshakes | awk '$2 > 0' | grep -q .")
 
+    with subtest("peer endpoint names are looked up again, but only for peers without a handshake"):
+        router.succeed("systemctl is-enabled router-wireguard-reresolve.timer")
+        router.succeed("wg show wg-ghost endpoints | grep -q 203.0.113.70:51830")
+        # The names now have other addresses.
+        router.succeed("rm /etc/hosts; printf '127.0.0.1 localhost\\n203.0.113.71 ghost.test\\n203.0.113.99 siteb.test\\n' > /etc/hosts")
+        router.succeed("systemctl start router-wireguard-reresolve.service")
+        router.succeed("wg show wg-ghost endpoints | grep -q 203.0.113.71:51830")
+        router.succeed("journalctl -u router-wireguard-reresolve --no-pager | grep -q 'endpoint 203.0.113.70:51830 -> 203.0.113.71:51830'")
+        # The working tunnel keeps its endpoint (it has a fresh handshake).
+        router.succeed("wg show wg-s2s endpoints | grep -q 203.0.113.60:51821")
+        # A name that does not resolve leaves the endpoint as it was.
+        router.succeed("printf '127.0.0.1 localhost\\n' > /etc/hosts")
+        router.succeed("systemctl start router-wireguard-reresolve.service")
+        router.succeed("wg show wg-ghost endpoints | grep -q 203.0.113.71:51830")
+        router.succeed("journalctl -u router-wireguard-reresolve --no-pager | grep -q 'ghost.test:51830'")
+        router.succeed("rm /etc/hosts; ln -s /etc/static/hosts /etc/hosts")
+
     with subtest("road warrior: dual-stack tunnel to the router, DNS and SSH over it"):
         laptop.succeed("ping -c 1 -W 2 10.100.0.1")
         laptop.succeed("ping -6 -c 1 -W 2 fd42:100::1")