mirror of https://github.com/jmcorgan/fips.git synced 2026-07-30 19:46:15 +00:00

Files

T

Johnathan Corgan cc7f967128 testing/mesh-lab: nat-lan cpu-pinning sidecar + trace overlay + stall_signature

Three deltas to the mesh-lab nat-lan suite for stall characterization:

- FIPS_NAT_LAN_CPUSET env-var-driven CPU-pinning sidecar in
  run_nat_lan, mirroring the bloom-storm pattern. Pinning is needed
  because the mesh-lab compose-resource-limits.yml override is
  rekey-family service-name specific (rekey-* / rekey-accept-off-* /
  rekey-outbound-only-*), so it does not constrain the nat-lan
  containers. Default cpuset 0,1 mimics a GHA 2-core runner; empty
  disables the sidecar.

- New compose-trace-nat.yml overlay that bumps RUST_LOG to trace on
  discovery::nostr, transport::udp, node::lifecycle,
  handlers::handshake, handlers::forwarding — the modules covering
  the cross-init / adoption / handshake path. Picked up by the
  nat-test.sh COMPOSE array via a new FIPS_NAT_EXTRA_COMPOSE
  colon-separated env-var hook. run_nat_lan sets this hook when
  FIPS_MESH_LAB_TRACE is non-empty; the README env-var section
  updated to reflect that FIPS_MESH_LAB_TRACE now applies to nat-lan
  in addition to the rekey-family.

- parse_nat_lan extended with a per-node stall_signature emitting
  last-occurrence timestamps for eight event categories (startup,
  discovery, adoption, handshake_init, msg2_sent, cross_init_ignore_*,
  handshake_failed) plus derived last_meaningful_event_ts,
  last_event_category, silent_gap_s. Top-level stall_class binned as
  no_timeout / silent / localized / distributed / incomplete from
  the per-node categories. Aggregation phase consumes the per-rep
  signatures across a characterization run to classify stall
  mechanism.

Wired support in nat-test.sh: FIPS_NAT_EXTRA_COMPOSE colon-separated
list of repo-relative or absolute compose files layered onto the
base via the COMPOSE array; FIPS_NAT_SKIP_FINAL_CLEANUP gates the
success-path teardown so the mesh-lab harness can capture docker
logs before tearing down (failure paths already returned without
cleanup, leaving stall-state containers intact for capture).

Smoke-tested on idle profile with TRACE on: 1 rep PASS, 32/36 TRACE
lines per node, signature.json events all populated with the
expected category timestamps.

2026-05-24 17:49:37 +00:00

node

Add Nostr-mediated overlay discovery and UDP NAT traversal (#53 )

2026-04-27 08:15:58 -07:00

relay

Add Nostr-mediated overlay discovery and UDP NAT traversal (#53 )

2026-04-27 08:15:58 -07:00

router

Add Nostr-mediated overlay discovery and UDP NAT traversal (#53 )

2026-04-27 08:15:58 -07:00

scripts

testing/mesh-lab: nat-lan cpu-pinning sidecar + trace overlay + stall_signature

2026-05-24 17:49:37 +00:00

stun

Add Nostr-mediated overlay discovery and UDP NAT traversal (#53 )

2026-04-27 08:15:58 -07:00

.gitignore

Add Nostr-mediated overlay discovery and UDP NAT traversal (#53 )

2026-04-27 08:15:58 -07:00

docker-compose.yml

Add stun-faults integration suite covering STUN failure/recovery

2026-05-03 21:06:09 +00:00

README.md

Add Nostr-mediated overlay discovery and UDP NAT traversal (#53 )

2026-04-27 08:15:58 -07:00

README.md

NAT Lab Harness

Real Docker-based NAT traversal integration tests for the mainline FIPS Nostr/STUN bootstrap path.

This harness spins up:

two FIPS nodes
a local Nostr relay
a local STUN server
one or two Linux router containers performing NAT with iptables

For the NAT scenarios, the node LAN interfaces are not attached to Docker bridge networks. The harness creates explicit veth pairs and moves them into the node and router namespaces after docker compose up so every packet must traverse the router namespace.

It covers three scenarios:

cone: both peers behind explicit namespace/veth full-cone emulation, UDP traversal succeeds
symmetric: both peers behind symmetric-style NAT, UDP traversal fails, TCP fallback succeeds
lan: both peers share a LAN subnet, LAN targets are preferred over reflexive addresses

NAT model notes

The harness does not rely on plain Docker MASQUERADE for the cone case.

cone
- uses explicit full-cone emulation in the router namespace
- outbound UDP is SNATed to the router WAN address while preserving the source port
- inbound UDP to the router WAN address is DNATed back to the single LAN host regardless of remote source
symmetric
- uses UDP MASQUERADE --random-fully
- outbound mappings may be port-randomized and are only reopened by matching conntrack state

This distinction matters because plain MASQUERADE is convenient source NAT, but it does not by itself model the "accept from any remote once mapped" behavior expected from a full-cone NAT.

Prerequisites

Docker with Compose support
locally built fips-test:latest

Build the test image with:

./testing/scripts/build.sh

Run

Run all scenarios:

./testing/nat/scripts/nat-test.sh

Run one scenario:

./testing/nat/scripts/nat-test.sh cone
./testing/nat/scripts/nat-test.sh symmetric
./testing/nat/scripts/nat-test.sh lan

Layout

docker-compose.yml
- relay/STUN/WAN topology plus container definitions
node/
- node bootstrap wrapper that waits for the injected veth interface
router/
- NAT router image and iptables setup
stun/
- minimal STUN binding responder
relay/
- local strfry config
scripts/generate-configs.sh
- derives ephemeral identities and writes per-scenario FIPS configs
scripts/setup-topology.sh
- injects and configures the NAT LAN veth pairs in the container namespaces
scripts/nat-test.sh
- boots the lab, waits for convergence, and asserts the resulting path

Assertions

cone
- both nodes connect
- connected transport is UDP
- active link remote addresses are on the WAN NAT subnet
symmetric
- NAT bootstrap does not establish a UDP link
- fallback converges
- connected transport is TCP via router-published WAN addresses
lan
- both nodes connect
- connected transport is UDP
- active link remote addresses stay on the shared LAN subnet