@adviser/ovn-fabric 0.1.2 → 0.1.4

package/src/generate-netns.ts

@@ -1,622 +0,0 @@
-// src/generate-netns.ts — emitUplinkNetns(): the netns-side setup
-// commands for one uplink (creates its netns, moves its real interface
-// in, wires up the transfer-link veth, brings up SLAAC/dhclient, and
-// configures NAT for whichever segments currently resolve to it).
-//
-// Pulled into generate-ovn.ts's single per-host script (see that
-// file's scriptForHost) rather than being its own standalone generator
-// — "one file, copy it, run it, everything is done" applies to the
-// whole topology, not per-tier. This file exists separately only to
-// keep generate-ovn.ts from growing unwieldy; it has no CLI surface
-// of its own.
-//
-// Scope: the netns side of each uplink's transfer link. This is the
-// direction SLAAC/DHCP actually need real kernel mechanism, not OVN
-// config:
-//   - IPv4: a DHCP client started directly on the real interface,
-//     inside the netns, backgrounded so this synchronous setup script
-//     can finish while lease acquisition continues independently.
-//     WHICH client (dhclient, dhcpcd, ...) is pluggable per uplink —
-//     see Uplink.discovery.client (types.ts) and emitIpv4Discovery
-//     below, which dispatches to one small emit function per client,
-//     all with the same idempotent shape. (ovn_uplink_sync.py
-//     supervises dhclient via a real systemd unit with Restart=always
-//     — this generator does not replace that level of supervision,
-//     only the one-time wiring.)
-//   - IPv6: kernel SLAAC autoconf via accept_ra. Forwarding (needed for
-//     routing between the veth and the real interface) SUPPRESSES RA
-//     acceptance unless accept_ra is explicitly set to 2 — confirmed
-//     live, this session — so this always sets accept_ra=2 on the real
-//     interface for any uplink with discovery.ipv6=slaac.
-//
-// NAT subnets are NOT stored on Uplink itself — they're derived by the
-// caller (generate-ovn.ts), at generation time, from which segments in
-// the same NetworkDefinition currently resolve (via
-// UplinkSelector.resolve()) to this uplink. Same "reflects resolution
-// AT GENERATION TIME" rule as the backbone join — re-run after
-// switching a segment's uplink to regenerate.
-//
-// Idempotent throughout: safe to re-run. Network namespace and
-// interface existence are checked before creating; iptables rules are
-// checked via -C before adding (iptables has no --may-exist).
-
-import type {
-  Backdoor,
-  DhcpClient,
-  InterfaceKind,
-  Segment,
-  Uplink,
-} from "./types.ts";
-
-function netnsName(u: Uplink): string {
-  return `ns-uplink-${u.name}`;
-}
-
-/** Real kernel interface an uplink's netns ultimately reaches the real
- * world (or, for "dummy" with no backdoor, a placeholder) through —
- * undefined for any InterfaceKind this generator can't wire up yet.
- * Shared by emitUplinkNetns (this uplink's own real interface) and the
- * backdoor NAT rule (the `via` uplink's real interface) so the
- * backdoor/vlan/dummy/physical dispatch only lives in one place.
- *
- * A real InterfaceKind (vlan/physical/wireguard) ALWAYS wins over a
- * backdoor, checked first below: an uplink can have both — a real
- * WireGuard tunnel needs its own bootstrap path to reach its peer at
- * all, which is exactly what a backdoor provides, but the TUNNEL is
- * still what's actually realIface for NAT/segment purposes, not the
- * backdoor's own veth (see emitBackdoorNat's fork on this same
- * check). Only when the uplink has NO real interface of its own (the
- * "dummy" placeholder kind) does the backdoor's netns-side veth (see
- * emitBackdoorVethAndRoute below) stand in as realIface instead.
- * Confirmed live, this session: an earlier version kept a separate,
- * address-less "dummy" device alongside the backdoor veth — two
- * interfaces for one job, with the actually-useful one (the backdoor
- * veth) never treated as `realIface` at all, so accept_ra/discovery/
- * NAT below never applied to it. One interface, not two — for the
- * dummy case. Added 2026-07-06 for real wireguard uplinks: same
- * principle, different fork of the SAME check. */
-function realIfaceFor(u: Uplink): string | undefined {
-  if (u.if.kind === "wireguard") return u.if.ifaceName;
-  if (u.backdoor !== undefined) return backdoorVethNetns(u.backdoor);
-  if (u.if.kind === "vlan") {
-    return u.if.ifaceName ?? `${u.if.vlanParent}.${u.if.vlanId}`;
-  }
-  if (u.if.kind === "dummy") return dummyIface(u);
-  if (u.if.kind === "physical") return u.if.name;
-  return undefined;
-}
-
-/** WireGuard: writes the conf file (built from `ifc.config` — see
- * WireguardInterfaceConfig, types.ts) to /etc/wireguard/<ifaceName>.conf
- * on the host, then shells out to `wg-quick up`, idempotently, inside
- * this uplink's own netns.
- *
- * The conf is written to a temp file first and compared (`cmp -s`)
- * against the real path before replacing it — same idempotency shape
- * as this script's own self-install step (generate-ovn.ts) — so an
- * unchanged config never bounces an already-up tunnel. Only when the
- * content actually changed does it bring the old tunnel down first
- * (wg-quick has no in-place reconfigure; the interface must be
- * recreated to pick up new keys/peers).
- *
- * `wg show <ifaceName>` is the idempotency check for actually bringing
- * it up: wg-quick has no --may-exist equivalent, but a running
- * interface with that name means it already did its job.
- *
- * NOTE: this embeds ifc.config.privateKey directly in the generated
- * script — see InterfaceKind's "wireguard" variant (types.ts) for why
- * that's a deliberate, explicit exception to this project's usual
- * credential-handling policy, not an oversight. */
-function emitWireguardInterface(
-  u: Uplink,
-  ns: string,
-  ifc: Extract<InterfaceKind, { kind: "wireguard" }>,
-): string[] {
-  const cfg = ifc.config;
-  const confPath = `/etc/wireguard/${ifc.ifaceName}.conf`;
-  const tmpPath = `/tmp/${ifc.ifaceName}.conf.new`;
-
-  const confBody = [
-    "[Interface]",
-    `PrivateKey = ${cfg.privateKey}`,
-    `Address = ${cfg.address}`,
-    ...(cfg.listenPort !== undefined ? [`ListenPort = ${cfg.listenPort}`] : []),
-    ...(cfg.dns !== undefined ? [`DNS = ${cfg.dns}`] : []),
-    "[Peer]",
-    `PublicKey = ${cfg.peer.publicKey}`,
-    `AllowedIPs = ${cfg.peer.allowedIps}`,
-    `Endpoint = ${cfg.peer.endpoint}`,
-    ...(cfg.peer.persistentKeepalive !== undefined
-      ? [`PersistentKeepalive = ${cfg.peer.persistentKeepalive}`]
-      : []),
-  ];
-
-  return [
-    `# --- wireguard: ${u.name} (${ifc.ifaceName}) ---`,
-    "mkdir -p /etc/wireguard",
-    "chmod 700 /etc/wireguard",
-    `cat > ${tmpPath} << 'WGCONF'`,
-    ...confBody,
-    "WGCONF",
-    `chmod 600 ${tmpPath}`,
-    `cmp -s ${tmpPath} ${confPath} 2>/dev/null && rm -f ${tmpPath} || {`,
-    `  ip netns exec ${ns} wg-quick down ${confPath} >/dev/null 2>&1 || true`,
-    `  mv ${tmpPath} ${confPath}`,
-    "}",
-    `ip netns exec ${ns} wg show ${ifc.ifaceName} >/dev/null 2>&1 || ` +
-      `ip netns exec ${ns} wg-quick up ${confPath}`,
-  ];
-}
-
-// Real kernel interface names (veth ends, the OVS bridge below) are
-// capped at IFNAMSIZ = 16 bytes including the NUL terminator, i.e. 15
-// usable characters — confirmed live, this session: "br-uplink-1280-
-// transfer" (23 chars) and "br-uplink-isp-primary-transfer" (30 chars)
-// both fail with ofproto "Invalid argument", and "veth-ovn-isp-modem"
-// (18 chars) would fail the same way. u.name is human-chosen and can
-// be arbitrarily long/descriptive (that's the point of it), so it must
-// NEVER be used to build a real interface name. u.slot is a small
-// sequential int (0-4095, unique per uplink, assigned by
-// NetworkBuilder — see types.ts) and is used here instead. OVN-side
-// logical object names (emitUplinkTransfer in generate-ovn.ts) are NOT
-// real interfaces — those keep u.name for readability.
-
-function vethOvn(u: Uplink): string {
-  return `veth-ovn-${u.slot}`;
-}
-
-function vethNetns(u: Uplink): string {
-  return `veth-krn-${u.slot}`;
-}
-
-/** OVS bridge that carries this uplink's transfer-link veth — must
- * match the bridge emitUplinkTransferInterface() (generate-ovn.ts)
- * creates and registers in ovn-bridge-mappings, so the OVN-side veth
- * created here has somewhere to attach. Slot-based name, not
- * name-based — see comment above. */
-export function uplinkTransferBridge(u: Uplink): string {
-  return `br-up-${u.slot}`;
-}
-
-/** Real kernel name of a "dummy" uplink's placeholder interface (see
- * InterfaceKind, types.ts) — slot-based, same IFNAMSIZ-safe convention
- * as vethOvn/vethNetns/uplinkTransferBridge above. Unlike those, this
- * one the generator actually CREATES (not just names) — see the "real
- * interface" block in emitUplinkNetns. */
-function dummyIface(u: Uplink): string {
-  return `dummy-up-${u.slot}`;
-}
-
-// ── ipv4 discovery: pluggable client ────────────────────────────────
-// discovery.ipv4 === "dhcp" says WHAT is needed (a DHCPv4 lease);
-// discovery.client says WHICH PROGRAM does it. Each client gets its
-// own tiny emit function, all with the same idempotent shape
-// ("already running for this interface? no-op : start it"), so the
-// generated script always has ONE clearly-labelled block per uplink
-// for this (see the "# --- ipv4 discovery: ..." comment below) instead
-// of the mechanism being buried inline. Adding a third client (or,
-// later, folding a WireGuard uplink into this same dispatch shape —
-// see WireGuard design discussion, 2026-07-06) means adding one
-// function and one switch arm here, not touching the two below.
-
-function emitDhclient(u: Uplink, ns: string, realIface: string): string[] {
-  return [
-    `ip netns exec ${ns} pgrep -f "dhclient.*${realIface}" >/dev/null || ` +
-      `ip netns exec ${ns} dhclient -nw ` +
-      `-pf /run/dhclient.${u.name}.pid ` +
-      `-lf /var/lib/dhcp/dhclient.${u.name}.leases ` +
-      `${realIface}`,
-  ];
-}
-
-function emitDhcpcd(u: Uplink, ns: string, realIface: string): string[] {
-  // NOTE: flags not yet verified against a live host — dhcpcd isn't
-  // installed on the reference deployment (only dhclient has been
-  // confirmed live so far). -b backgrounds immediately, -q quiets normal
-  // output. Idempotency uses the same pgrep guard as the dhclient
-  // branch above rather than a hardcoded pidfile path, since dhcpcd's
-  // default pidfile naming varies by distro/version.
-  return [
-    `ip netns exec ${ns} pgrep -f "dhcpcd.*${realIface}" >/dev/null || ` +
-      `ip netns exec ${ns} dhcpcd -b -q ${realIface}`,
-  ];
-}
-
-/** client === "static": not a program at all, just configure the fixed
- * address + default gateway directly (see StaticIpv4, types.ts) —
- * what dhclient/dhcpcd would otherwise learn dynamically. Useful for
- * an uplink that turns out to want a stable reserved LAN address
- * rather than whatever the router's DHCP server hands out. Same
- * idempotent shape as the two above, just no client process
- * to check for — only the address and the route. */
-function emitStaticIpv4(u: Uplink, ns: string, realIface: string): string[] {
-  const cfg = u.discovery?.static4;
-  if (cfg === undefined) {
-    return [
-      `# WARNING: client "static" requested for ${u.name} but no ` +
-        `discovery.static4 given — nothing configured, see types.ts`,
-    ];
-  }
-  const addrHost = cfg.address.split("/")[0];
-  return [
-    `ip netns exec ${ns} ip addr show ${realIface} | grep -q ${addrHost} || ` +
-      `ip netns exec ${ns} ip addr add ${cfg.address} dev ${realIface}`,
-    `ip netns exec ${ns} ip route show | grep -q '^default' || ` +
-      `ip netns exec ${ns} ip route add default via ${cfg.gateway} dev ${realIface}`,
-  ];
-}
-
-function emitIpv4Discovery(
-  u: Uplink,
-  ns: string,
-  realIface: string,
-): string[] {
-  // Explicit client always wins. With none given, fall back to
-  // "dhclient" — but ONLY when discovery.ipv4 is "dhcp" (the
-  // historical default for a real WAN uplink). A "static"
-  // discovery.ipv4 with NO explicit client — e.g. a backdoor's merged
-  // real interface (see realIfaceFor above), whose address/route are
-  // already fully handled by emitBackdoorVethAndRoute — deliberately
-  // does nothing here at all.
-  const client: DhcpClient | undefined = u.discovery?.client ??
-    (u.discovery?.ipv4 === "dhcp" ? "dhclient" : undefined);
-  if (client === undefined) return [];
-
-  const lines = [`# --- ipv4 discovery: ${client} on ${realIface} ---`];
-  switch (client) {
-    case "dhclient":
-      lines.push(...emitDhclient(u, ns, realIface));
-      break;
-    case "dhcpcd":
-      lines.push(...emitDhcpcd(u, ns, realIface));
-      break;
-    case "static":
-      lines.push(...emitStaticIpv4(u, ns, realIface));
-      break;
-  }
-  return lines;
-}
-
-export function emitUplinkNetns(
-  u: Uplink,
-  segmentsOnThisUplink: readonly Segment[],
-): string[] {
-  const ns = netnsName(u);
-  const vOvn = vethOvn(u);
-  const vNetns = vethNetns(u);
-
-  const realIface = realIfaceFor(u);
-  if (realIface === undefined) {
-    return [
-      `# unsupported uplink interface kind "${u.if.kind}" for ${u.name} ` +
-        `— skipped, see generate-netns.ts`,
-      "",
-    ];
-  }
-
-  const ovnSide = u.addresses[0]; // host=1
-  const netnsSide = u.addresses[1]; // host=2
-
-  const lines: string[] = [`# --- uplink: ${u.name} (netns side) ---`];
-
-  // netns + veth pair (idempotent)
-  lines.push(
-    // `ip netns list` prints "<name> (id: N)", not just "<name>" — a
-    // plain `grep -qx ${ns}` (exact whole-line match) never matches an
-    // existing namespace, so a re-run always tries `ip netns add`
-    // again and fails with "File exists" under `set -e`, aborting
-    // everything after it (confirmed live, this session — the same
-    // "safe to re-run" idempotency this generator is built around).
-    // Isolate just the name field first, then match exactly.
-    `ip netns list | awk '{print $1}' | grep -qx ${ns} || ip netns add ${ns}`,
-    `ip netns exec ${ns} ip link set lo up`,
-    `ip link show ${vOvn} >/dev/null 2>&1 || ` +
-      `ip link add ${vOvn} type veth peer name ${vNetns}`,
-    // Move the netns-side veth end over. Checking "is ${vNetns}
-    // visible in the root namespace" (not "is it absent") is the
-    // correct idempotency test: right after creation both veth ends
-    // exist in the root ns, so a check for absence never fires and
-    // the move never happens on first run — confirmed live, this
-    // session ("Cannot find device" on the subsequent `ip netns exec
-    // ... set up`, because the interface was still sitting in root).
-    // If ${vNetns} is NOT visible in root, it's already been moved by
-    // a prior run — nothing to do, `|| true` makes that a no-op.
-    `ip link show ${vNetns} >/dev/null 2>&1 && ` +
-      `ip link set ${vNetns} netns ${ns} || true`,
-    // Attach the OVN-side veth to its transfer-link OVS bridge —
-    // without this, ovn-bridge-mappings has nothing plugged into it
-    // and the localnet port never sees traffic (confirmed live: a
-    // bridge existing with no port attached errors on ofproto add).
-    `ovs-vsctl --may-exist add-port ${uplinkTransferBridge(u)} ${vOvn}`,
-    `ip link set ${vOvn} up`,
-    `ip netns exec ${ns} ip link set ${vNetns} up`,
-    `ip addr show ${vOvn} | grep -q ${ovnSide.ipv4.to_s()} || ` +
-      `ip addr add ${ovnSide.ipv4.to_string()} dev ${vOvn}`,
-    `ip addr show ${vOvn} | grep -q ${ovnSide.ipv6.to_s()} || ` +
-      `ip addr add ${ovnSide.ipv6.to_string()} dev ${vOvn}`,
-    `ip netns exec ${ns} sh -c "ip addr show ${vNetns} | grep -q ` +
-      `${netnsSide.ipv4.to_s()} || ip addr add ${netnsSide.ipv4.to_string()} ` +
-      `dev ${vNetns}"`,
-    `ip netns exec ${ns} sh -c "ip addr show ${vNetns} | grep -q ` +
-      `${netnsSide.ipv6.to_s()} || ip addr add ${netnsSide.ipv6.to_string()} ` +
-      `dev ${vNetns}"`,
-  );
-
-  // real interface: create if missing, move into netns.
-  //
-  // The backdoor's own veth+route (if any) is emitted UNCONDITIONALLY
-  // here, regardless of whether this uplink ALSO has a real interface
-  // of its own — it's a separate, always-useful bootstrap path (see
-  // Backdoor, types.ts), not a substitute for one except in the
-  // "dummy" placeholder case (see realIfaceFor above).
-  if (u.backdoor !== undefined) {
-    lines.push(...emitBackdoorVethAndRoute(u, u.backdoor));
-  }
-  if (u.if.kind === "wireguard") {
-    // A real interface of its own — created here alongside (not
-    // instead of) the backdoor block above.
-    lines.push(...emitWireguardInterface(u, ns, u.if));
-  } else if (u.backdoor === undefined) {
-    // No backdoor AND no wireguard tunnel: fall through to the plain
-    // vlan/dummy/physical creation. (When a backdoor IS present and
-    // `u.if.kind === "dummy"`, realIface already resolved to the
-    // backdoor's own veth above — nothing further to create here; see
-    // realIfaceFor's doc comment.)
-    lines.push(
-      `ip netns exec ${ns} ip link show ${realIface} >/dev/null 2>&1 || {`,
-      `  ip link show ${realIface} >/dev/null 2>&1 || ` +
-        (u.if.kind === "vlan"
-          ? `ip link add link ${u.if.vlanParent} name ${realIface} ` +
-            `type vlan id ${u.if.vlanId}`
-          : u.if.kind === "dummy"
-          ? `ip link add ${realIface} type dummy`
-          : `true # physical interface ${realIface} must already exist`),
-      `  ip link set ${realIface} netns ${ns}`,
-      `}`,
-      `ip netns exec ${ns} ip link set ${realIface} up`,
-    );
-  }
-
-  // forwarding + back-routes (kernel-side, not arithmetic — plain shell)
-  lines.push(
-    `ip netns exec ${ns} sysctl -qw net.ipv4.ip_forward=1`,
-    `ip netns exec ${ns} sysctl -qw net.ipv6.conf.all.forwarding=1`,
-    `ip netns exec ${ns} ip route show | grep -q '^10.0.0.0/8' || ` +
-      `ip netns exec ${ns} ip route add 10.0.0.0/8 via ${ovnSide.ipv4.to_s()} dev ${vNetns}`,
-    `ip netns exec ${ns} ip route show | grep -q '^192.168.0.0/16' || ` +
-      `ip netns exec ${ns} ip route add 192.168.0.0/16 via ${ovnSide.ipv4.to_s()} dev ${vNetns}`,
-    `ip netns exec ${ns} ip -6 route show | grep -q '^fd00::/8' || ` +
-      `ip netns exec ${ns} ip -6 route add fd00::/8 via ${ovnSide.ipv6.to_s()} dev ${vNetns}`,
-  );
-
-  // discovery: SLAAC needs accept_ra=2 (forwarding suppresses RA
-  // otherwise — confirmed live, this session). DHCPv4 needs dhclient
-  // started on the real interface, inside the netns.
-  if (u.discovery?.ipv6 === "slaac") {
-    lines.push(
-      `ip netns exec ${ns} sh -c "echo 2 > ` +
-        `/proc/sys/net/ipv6/conf/${realIface}/accept_ra"`,
-    );
-  }
-  lines.push(...emitIpv4Discovery(u, ns, realIface));
-
-  // NAT: derived by the caller from which segments currently resolve
-  // to this uplink — NOT stored on Uplink itself, see header comment.
-  // segAddr.to_string() below is the segment's GATEWAY host address
-  // with the segment's prefix length (e.g. 192.168.128.2/24, not
-  // 192.168.128.0/24) — this is intentional and correct, not a bug:
-  // iptables/ip6tables (and IPAddress.parse non-strict) both mask a
-  // host address by its prefix length before matching, so
-  // "-s 192.168.128.2/24" matches the entire 192.168.128.0/24 network
-  // exactly the same as writing the bare network address would.
-  for (const seg of segmentsOnThisUplink) {
-    const segAddr = seg.addresses[0];
-    if (u.nat?.ipv4?.some((r) => r.kind === "masq")) {
-      lines.push(
-        `ip netns exec ${ns} iptables -t nat -C POSTROUTING -s ` +
-          `${segAddr.ipv4.to_string()} -o ${realIface} -j MASQUERADE 2>/dev/null || ` +
-          `ip netns exec ${ns} iptables -t nat -A POSTROUTING -s ` +
-          `${segAddr.ipv4.to_string()} -o ${realIface} -j MASQUERADE`,
-      );
-    }
-    if (u.nat?.ipv6?.some((r) => r.kind === "masq")) {
-      lines.push(
-        `ip netns exec ${ns} ip6tables -t nat -C POSTROUTING -s ` +
-          `${segAddr.ipv6.to_string()} -o ${realIface} -j MASQUERADE 2>/dev/null || ` +
-          `ip netns exec ${ns} ip6tables -t nat -A POSTROUTING -s ` +
-          `${segAddr.ipv6.to_string()} -o ${realIface} -j MASQUERADE`,
-      );
-    }
-  }
-
-  lines.push("");
-  return lines;
-}
-
-// ── backdoor: borrowed egress for a VPN-like uplink ─────────────────
-// See Backdoor (types.ts) for the why. The kernel-side shape here is
-// deliberately the SAME veth-pair/address/route dance as a normal
-// transfer link (emitUplinkNetns above) — a backdoor IS a transfer
-// link, just one whose OVN-side lands on an ALREADY-real uplink's
-// router instead of spinning up a dedicated one of its own. The one
-// thing that must NOT be reused is the address block: bd.addresses
-// comes from its own slot (see factories.ts, uplinkDummy), so it can
-// never share a /28 with `u`'s own front-door transfer link — sharing
-// one was tried and is broken (see Backdoor's doc comment for why).
-
-function backdoorVethOvn(bd: Backdoor): string {
-  return `veth-bdo-${bd.slot}`;
-}
-
-function backdoorVethNetns(bd: Backdoor): string {
-  return `veth-bdk-${bd.slot}`;
-}
-
-/** OVS bridge carrying a backdoor's own veth — must match the bridge
- * emitBackdoorInterface() (generate-ovn.ts) creates and registers in
- * ovn-bridge-mappings. Slot-based, same convention as
- * uplinkTransferBridge() above. */
-export function backdoorBridge(bd: Backdoor): string {
-  return `br-bd-${bd.slot}`;
-}
-
-/** Creates the backdoor's own veth pair, addresses both ends, and adds
- * the default route out through it — this IS u's real interface (see
- * realIfaceFor above), not a separate placeholder alongside one, so
- * it's called from emitUplinkNetns's "real interface" section, in the
- * exact spot a plain vlan/dummy/physical device would otherwise be
- * created. NAT is deliberately NOT here — see emitBackdoorNat below,
- * called separately since it targets `via`'s netns, not this one. */
-export function emitBackdoorVethAndRoute(u: Uplink, bd: Backdoor): string[] {
-  const ns = netnsName(u);
-  const vOvn = backdoorVethOvn(bd);
-  const vNetns = backdoorVethNetns(bd);
-  const ovnSide = bd.addresses[0]; // host=3, lives on the `via` router
-  const netnsSide = bd.addresses[1]; // host=4, lives in this uplink's netns
-
-  const lines: string[] = [
-    `# --- backdoor: ${u.name} -> ${bd.via.name} (borrowed egress, netns side) ---`,
-  ];
-
-  // veth pair: OVN side stays in root, netns side moves into THIS
-  // uplink's own netns (not `via`'s) — same idempotency reasoning as
-  // emitUplinkNetns's own veth pair above.
-  lines.push(
-    `ip link show ${vOvn} >/dev/null 2>&1 || ` +
-      `ip link add ${vOvn} type veth peer name ${vNetns}`,
-    `ip link show ${vNetns} >/dev/null 2>&1 && ` +
-      `ip link set ${vNetns} netns ${ns} || true`,
-    `ovs-vsctl --may-exist add-port ${backdoorBridge(bd)} ${vOvn}`,
-    `ip link set ${vOvn} up`,
-    `ip netns exec ${ns} ip link set ${vNetns} up`,
-    `ip addr show ${vOvn} | grep -q ${ovnSide.ipv4.to_s()} || ` +
-      `ip addr add ${ovnSide.ipv4.to_string()} dev ${vOvn}`,
-    `ip addr show ${vOvn} | grep -q ${ovnSide.ipv6.to_s()} || ` +
-      `ip addr add ${ovnSide.ipv6.to_string()} dev ${vOvn}`,
-    `ip netns exec ${ns} sh -c "ip addr show ${vNetns} | grep -q ` +
-      `${netnsSide.ipv4.to_s()} || ip addr add ${netnsSide.ipv4.to_string()} ` +
-      `dev ${vNetns}"`,
-    `ip netns exec ${ns} sh -c "ip addr show ${vNetns} | grep -q ` +
-      `${netnsSide.ipv6.to_s()} || ip addr add ${netnsSide.ipv6.to_string()} ` +
-      `dev ${vNetns}"`,
-  );
-
-  // Default route via the backdoor — deliberately just the DEFAULT
-  // route, not a broad backroute like emitUplinkNetns's 10.0.0.0/8 /
-  // 192.168.0.0/16: this uplink's netns ALSO has its own front-door
-  // transfer link (more specific routes there, if any exist), and
-  // those must keep winning for anything internal. Only genuinely
-  // internet-bound traffic (not matched by anything more specific)
-  // should fall through to the backdoor.
-  lines.push(
-    `ip netns exec ${ns} ip route show | grep -q '^default' || ` +
-      `ip netns exec ${ns} ip route add default via ${ovnSide.ipv4.to_s()} dev ${vNetns}`,
-    `ip netns exec ${ns} ip -6 route show | grep -q '^default' || ` +
-      `ip netns exec ${ns} ip -6 route add default via ${ovnSide.ipv6.to_s()} dev ${vNetns}`,
-  );
-
-  lines.push("");
-  return lines;
-}
-
-/** NAT for traffic borrowing this backdoor's egress — lives in `via`'s
- * netns (the uplink with the real interface), NOT this uplink's own
- * netns, since masquerading has to happen where the real interface
- * actually is. Called separately from emitBackdoorVethAndRoute (from
- * generate-ovn.ts, alongside every other uplink's own NAT) rather than
- * folded into it, since it targets a different netns entirely.
- *
- * Scoped to `via`'s OWN declared nat config (bd.via.nat), exactly like
- * segment NAT above is scoped to the resolving uplink's nat config —
- * NOT unconditional (an earlier version added this rule regardless of
- * whether `via` even wants NAT, per feedback 2026-07-06: "we do nat on
- * the avm uplink").
- *
- * WHAT gets matched forks on whether the backdoor is standing in as
- * `u`'s own realIface (see realIfaceFor above) or merely bootstrapping
- * a SEPARATE real interface (e.g. a wireguard tunnel):
- *
- *   - No real interface of its own (the "dummy" placeholder case): the
- *     backdoor's netns-side veth IS realIface, so actual segment
- *     traffic really does flow through it — matches on each SEGMENT's
- *     own subnet (segAddr below), e.g. 192.168.130.0/24 for
- *     "neighbor", exactly like emitUplinkNetns's own segment-NAT loop.
- *     NOT bd.addresses: routed segment traffic keeps its original
- *     source address all the way through the OVN topology (every hop
- *     here is routing, not NAT), so that's the address that has to
- *     appear in the rule. Confirmed live, 2026-07-06 — an earlier
- *     version matched on bd.addresses here unconditionally and
- *     silently NAT'd nothing useful (nmap against that /28 only ever
- *     found the backdoor's own interface answering).
- *
- *   - A real interface of its own (e.g. wireguard): the backdoor
- *     carries ONLY that interface's own bootstrap/handshake/keepalive
- *     traffic (once it's up, real segment traffic goes through the
- *     tunnel instead, matched by u's OWN nat/realIface in
- *     emitUplinkNetns's segment-NAT loop, same as every non-backdoor
- *     uplink). That bootstrap traffic is sourced from the backdoor's
- *     OWN transit address (bd.addresses[1]), never from a segment
- *     subnet — so THAT'S what gets matched here instead.
- *
- * Requires `via`'s netns to already exist by the time this runs — true
- * as long as `via` is declared (and therefore processed) before this
- * uplink, which NetworkBuilder enforces (see define.ts). */
-export function emitBackdoorNat(
-  u: Uplink,
-  segmentsOnThisUplink: readonly Segment[],
-): string[] {
-  const bd = u.backdoor;
-  if (bd === undefined) return [];
-
-  const viaNs = netnsName(bd.via);
-  const viaRealIface = realIfaceFor(bd.via);
-  if (viaRealIface === undefined) return [];
-
-  const lines: string[] = [];
-
-  if (realIfaceFor(u) === backdoorVethNetns(bd)) {
-    // Backdoor IS u's realIface — NAT scoped per resolving segment.
-    for (const seg of segmentsOnThisUplink) {
-      const segAddr = seg.addresses[0];
-      if (bd.via.nat?.ipv4?.some((r) => r.kind === "masq")) {
-        lines.push(
-          `ip netns exec ${viaNs} iptables -t nat -C POSTROUTING -s ` +
-            `${segAddr.ipv4.to_string()} -o ${viaRealIface} -j MASQUERADE 2>/dev/null || ` +
-            `ip netns exec ${viaNs} iptables -t nat -A POSTROUTING -s ` +
-            `${segAddr.ipv4.to_string()} -o ${viaRealIface} -j MASQUERADE`,
-        );
-      }
-      if (bd.via.nat?.ipv6?.some((r) => r.kind === "masq")) {
-        lines.push(
-          `ip netns exec ${viaNs} ip6tables -t nat -C POSTROUTING -s ` +
-            `${segAddr.ipv6.to_string()} -o ${viaRealIface} -j MASQUERADE 2>/dev/null || ` +
-            `ip netns exec ${viaNs} ip6tables -t nat -A POSTROUTING -s ` +
-            `${segAddr.ipv6.to_string()} -o ${viaRealIface} -j MASQUERADE`,
-        );
-      }
-    }
-  } else {
-    // u has its own real interface (e.g. wireguard) — backdoor only
-    // carries ITS bootstrap traffic, sourced from the backdoor's own
-    // transit address, not any segment.
-    const netnsSide = bd.addresses[1];
-    if (bd.via.nat?.ipv4?.some((r) => r.kind === "masq")) {
-      lines.push(
-        `ip netns exec ${viaNs} iptables -t nat -C POSTROUTING -s ` +
-          `${netnsSide.ipv4.to_string()} -o ${viaRealIface} -j MASQUERADE 2>/dev/null || ` +
-          `ip netns exec ${viaNs} iptables -t nat -A POSTROUTING -s ` +
-          `${netnsSide.ipv4.to_string()} -o ${viaRealIface} -j MASQUERADE`,
-      );
-    }
-    if (bd.via.nat?.ipv6?.some((r) => r.kind === "masq")) {
-      lines.push(
-        `ip netns exec ${viaNs} ip6tables -t nat -C POSTROUTING -s ` +
-          `${netnsSide.ipv6.to_string()} -o ${viaRealIface} -j MASQUERADE 2>/dev/null || ` +
-          `ip netns exec ${viaNs} ip6tables -t nat -A POSTROUTING -s ` +
-          `${netnsSide.ipv6.to_string()} -o ${viaRealIface} -j MASQUERADE`,
-      );
-    }
-  }
-
-  return lines;
-}