Merge branch 'master' into next

Forward-merge of 12 master commits past the previous merge (823b830, master @ 18019bb): dep-audit bumps (rand, clap, tun, rtnetlink, windows-service, plus the bump-safe lockfile batch), bloom-storm chaos scenario, control-socket resolver consolidation, gateway dns.listen default change, OpenWrt ipk README refresh, gateway tutorial review, Ethernet MTU rustdoc fix, dead session-variant drop, CHANGELOG prep. Conflict resolution: - CHANGELOG.md: both bullets kept under [Unreleased] / Fixed. Master's spanning-tree internal-path-propagation fix precedes next's tree-ancestry-test determinism entry and the responder-Disconnect XX-handshake entry. - src/protocol/session.rs: kept next's SessionSetup/SessionAck variants and rustdoc. Master's drop of those variants suits v0.3.0's FSP phase-byte dispatch but is undone by next's v0.4.0 wire format, which retains the variants and uses the inner msg_type byte for handshake identification. - src/transport/ethernet/mod.rs: kept next's "interface MTU - 4" comment. Master corrected the v0.3.0 3-byte rustdoc; next redesigned the framing to a 4-byte header (type/flags/length) for shared-media beacons, so master's correction does not apply to next's format. Auto-merged cleanly: Cargo.toml (next's 0.4.0-dev + the new dep pins from master), Cargo.lock, all gateway docs, docs/reference/configuration.md, packaging files, .github/workflows/ci.yml, testing/chaos/sim/* and testing/ci-local.sh (bloom-storm additions), src/config/*. Local verification: cargo build --release, cargo test (1252 passed, 4 ignored), cargo clippy -D warnings, cargo fmt --check all green.
2026-08-11 00:47:39 +00:00 · 2026-05-08 18:47:13 +00:00
parent 823b830289 b3a1fb464f
commit 45a8a4cd9b
26 changed files with 1518 additions and 434 deletions
@@ -130,7 +130,7 @@ There is no `fipsctl gateway` subcommand; clients (including
            │                                   │
            │  ┌──────────────┐  ┌───────────┐  │
            │  │   DNS proxy  │  │  Virtual  │  │
-            │  │   ([::]:53)  │─▶│  IP pool  │  │
+            │  │ ([::1]:5353) │─▶│  IP pool  │  │
            │  │   .fips only │  │ (state    │  │
            │  └──────┬───────┘  │  machine) │  │
            │         │          └─────┬─────┘  │
@@ -182,13 +182,18 @@ involving the DNS proxy or the pool.
 ### DNS Resolution Flow

 1. A LAN client sends a DNS query to the gateway's listener (default
-   `[::]:53`, configurable via `gateway.dns.listen`).
+   `[::1]:5353`, configurable via `gateway.dns.listen`). The default
+   is loopback-only on an unprivileged port: the canonical deployment
+   has another resolver on the host (dnsmasq, systemd-resolved, BIND)
+   holding port 53 and forwarding `.fips` queries to the gateway over
+   loopback. Operators on a host without a pre-existing resolver on
+   53 can override the listen value to `"[::]:53"` to let LAN clients
+   query the gateway directly.
 2. If the question is not for a `.fips` domain, the gateway replies
   `REFUSED`. The proxy is intentionally narrow — it does not resolve
   public DNS, and the LAN's primary resolver should hold port 53 on
-   the gateway host (the OpenWrt init script wires this up by binding
-   the gateway listener to a non-conflicting port and configuring
-   dnsmasq to forward `.fips` queries there).
+   the gateway host (the OpenWrt init script wires dnsmasq to forward
+   `.fips` queries to the loopback listener automatically).
 3. The gateway forwards the query to the daemon resolver
   (`gateway.dns.upstream`, default `[::1]:5354`). The daemon must
   match: an IPv6 socket bound to `[::1]` does not accept v4-mapped
@@ -142,7 +142,7 @@ pick a different `fdXX::/N`). The `/112` size yields 65 536 virtual
 IPs, which is the gateway's hard cap regardless of CIDR width.

 This minimum config is enough to start the gateway. The `dns.*` block
-is optional and defaults to `listen: "[::]:53"` and
+is optional and defaults to `listen: "[::1]:5353"` and
 `upstream: "[::1]:5354"`. The full block — including `dns.*`,
 `pool_grace_period`, `conntrack.*`, and `port_forwards[]` — is
 documented in
@@ -195,20 +195,28 @@ Constraints:
 ```yaml
 gateway:
  dns:
-    listen: "[::]:53"
+    listen: "[::1]:5353"
    upstream: "[::1]:5354"
    ttl: 60
 ```

 Common cases:

- **No other resolver on the host:** `listen: "[::]:53"` is the
-  default and works.
- **systemd-resolved is on port 53:** either disable its stub
-  listener (`DNSStubListener=no` in
-  `/etc/systemd/resolved.conf`) or move the gateway to a different
-  port (e.g., `[::]:5353`) and put a forwarder on 53 that delegates
-  `.fips` to the gateway. See
+- **Another resolver on the host (the canonical case):** the default
+  `listen: "[::1]:5353"` is loopback-only on an unprivileged port,
+  so it never conflicts with dnsmasq, systemd-resolved, or BIND
+  holding 53. Configure the existing resolver to forward `.fips`
+  queries to `[::1]:5353` and you are done — this is what the
+  OpenWrt ipk does automatically.
+- **No other resolver on the host:** set `listen: "[::]:53"`
+  explicitly and LAN clients can query the gateway directly.
+- **systemd-resolved is on port 53:** the default already side-steps
+  this — leave the listen address at `[::1]:5353` and configure the
+  stub or a small forwarder to delegate `.fips` to the gateway. If
+  you would rather have the gateway on 53 directly, disable the
+  systemd stub listener (`DNSStubListener=no` in
+  `/etc/systemd/resolved.conf`) and switch `listen` to `"[::]:53"`.
+  See
  [troubleshoot-gateway.md](troubleshoot-gateway.md#port-conflict-on-the-dns-listen-port).
 - **Bind on the LAN address only:** `listen: "192.168.1.1:53"`
  exposes the resolver only to LAN clients, not loopback.
@@ -82,10 +82,13 @@ for the full flag list.
 ### Port conflict on the DNS listen port

 Symptom: gateway fails to start with "address already in use" on
-port 53 (or whatever `gateway.dns.listen` is set to).
+the configured `gateway.dns.listen` address.

-Another DNS server (systemd-resolved, dnsmasq, BIND) is bound to
-the port. Identify it:
+The default `[::1]:5353` is loopback-only on an unprivileged port and
+should not collide with any standard resolver. If you have overridden
+`dns.listen` to bind port 53 (or a LAN-side address) and another DNS
+server (systemd-resolved, dnsmasq, BIND) is already bound there,
+identify it:

 ```sh
 sudo ss -tulnp | grep ':53'
@@ -93,18 +96,10 @@ sudo ss -tulnp | grep ':53'

 Two options:

- **Use an alternate listen address.** Pick a non-conflicting port
-  and update the gateway config:
-
-  ```yaml
-  gateway:
-    dns:
-      listen: "192.168.1.1:5353"
-  ```
-
-  Then either point LAN clients at the alternate port directly, or
-  run a forwarding stub on port 53 that delegates `.fips` queries to
-  the gateway.
+- **Stay on the loopback default.** Drop the override and let the
+  gateway use `[::1]:5353`. Configure the existing resolver to
+  forward `.fips` queries to it (the canonical OpenWrt deployment
+  works this way out of the box).

 - **Relocate the conflicting resolver.** Move it to a different port
  (or disable it if not needed) and let the gateway bind 53.
@@ -189,7 +184,7 @@ not running or not enabled. Check that the daemon config has
 **Step 2.** Verify the gateway is listening on its DNS port:

 ```sh
-sudo ss -tulnp | grep -E ':53\b'
+sudo ss -tulnp | grep -E ':(53|5353)\b'
 ```

 If nothing is listening on the configured `dns.listen` address, the
@@ -700,7 +700,7 @@ Non-`.fips` queries are answered with `REFUSED`.

 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `gateway.dns.listen` | string | `"[::]:53"` | LAN-facing DNS listen address. Bind on the LAN-side IP (e.g., `"192.168.1.1:53"`) or on all interfaces (`"[::]:53"`) for LAN clients to query. Bind to a non-53 port if another resolver already owns 53 on the host (see [../how-to/troubleshoot-gateway.md](../how-to/troubleshoot-gateway.md)). |
+| `gateway.dns.listen` | string | `"[::1]:5353"` | DNS listen address. The default binds IPv6 loopback on an unprivileged port, matching the canonical deployment where another resolver on the host (dnsmasq, systemd-resolved, BIND) holds port 53 and forwards `.fips` queries to the gateway over loopback. Bind on the LAN-side IP (e.g., `"192.168.1.1:53"`) or wildcard (`"[::]:53"`) only on hosts with no other resolver on 53 and where LAN clients query the gateway directly. See [../how-to/troubleshoot-gateway.md](../how-to/troubleshoot-gateway.md). |
 | `gateway.dns.upstream` | string | `"[::1]:5354"` | Upstream FIPS daemon resolver. **Must match the daemon's `dns.bind_addr` and `dns.port`.** Defaults match the daemon defaults (`::1:5354`). A v4 upstream (`"127.0.0.1:5354"`) cannot reach a daemon bound on `[::1]:5354` — Linux IPv6 sockets bound to explicit `::1` do not accept v4-mapped traffic. If you change the daemon's `dns.bind_addr`, update this field accordingly. |
 | `gateway.dns.ttl` | u32 | `60` | TTL in seconds on AAAA responses returned to LAN clients. Smaller values let the gateway recycle pool addresses faster; larger values reduce LAN-side query traffic. |

@@ -747,7 +747,7 @@ gateway:
  pool: "fd01::/112"
  lan_interface: "enp3s0"
  dns:
-    listen: "[::]:53"
+    listen: "[::1]:5353"
    upstream: "[::1]:5354"
    ttl: 60
  pool_grace_period: 60
@@ -132,7 +132,6 @@ gateway:
  pool: "fd01::/112"            # virtual IP range (up to 65535 addresses)
  lan_interface: "br-lan"       # LAN-facing interface for proxy NDP
  dns:
-    listen: "[::1]:5353"        # gateway DNS listener (dnsmasq forwards here)
    upstream: "[::1]:5354"      # FIPS daemon DNS resolver (matches daemon default)
    ttl: 60                     # DNS TTL and mapping lifetime (seconds)
  pool_grace_period: 60         # seconds after last session before reclaiming
@@ -147,10 +146,11 @@ Three things to notice:
 - `lan_interface: "br-lan"` — the OpenWrt LAN bridge. The gateway
  installs proxy-NDP entries on this interface so LAN clients can
  ARP-equivalent for pool addresses.
- `dns.listen: "[::1]:5353"` — the gateway's DNS listener is bound
-  to IPv6 loopback only. dnsmasq, which owns LAN port 53, forwards
-  `.fips` queries to it. The init script wires up that forwarding;
-  you don't bind to a LAN address yourself.
+- No `dns.listen` line — the source default `[::1]:5353` is exactly
+  what OpenWrt wants. The gateway listens on IPv6 loopback only;
+  dnsmasq, which owns LAN port 53, forwards `.fips` queries to it.
+  The init script wires up that forwarding; you don't bind to a LAN
+  address yourself.

 For the full reference, see
 [../reference/configuration.md § Gateway](../reference/configuration.md#gateway-gateway).
@@ -207,8 +207,21 @@ table install, and pool initialisation.

 ## Step 4: Test the outbound half from a LAN client

-From a phone or laptop on the AP's LAN — anything that does IPv6 and
-DNS, with no FIPS software installed — try one of the public test
+Before bringing a LAN client into the picture, confirm from the AP
+itself that the mesh side is still healthy after the gateway start:
+
+```sh
+ping6 -c 2 test-us01.fips
+```
+
+This isolates the router-to-mesh path before involving the LAN
+segment. If this fails, the troubleshooting target is the daemon /
+mesh side, not the gateway-to-client side. If it succeeds and the
+LAN-client test below fails, the target is the LAN segment —
+`proxy_ndp`, the RA pool route, or DNS forwarding through dnsmasq.
+
+Now from a phone or laptop on the AP's LAN — anything that does IPv6
+and DNS, with no FIPS software installed — try one of the public test
 mesh nodes:

 ```sh
@@ -272,7 +285,7 @@ nft list table inet fips_gateway
 You will see DNAT, SNAT, and masquerade chains populated with one
 rule per active mapping.

-## Step 6: Add an inbound port-forward for a LAN service
+## Step 6 (Optional): Add an inbound port-forward for a LAN service

 The outbound half is the steady-state use of a gateway. The inbound
 half — exposing a LAN service to mesh peers — is a separate decision,
@@ -321,7 +334,6 @@ gateway:
  pool: "fd01::/112"
  lan_interface: "br-lan"
  dns:
-    listen: "[::1]:5353"
    upstream: "[::1]:5354"
    ttl: 60
  pool_grace_period: 60