Johnathan Corgan
26cfb4fad3
The peer ACL changelog entry joins master's existing Links and transports section under Security rather than opening a second one. testing/root-tests.sh carries master's filters rather than maint's, in two groups: the TUN warning, DNS responder and gateway mesh tests (18), and the Linux TUN namespace tests (13). It needs ip, nft and sysctl here, and its probe also writes a sysctl inside the namespace, as four of the TUN tests do, so a container with a read-only /proc/sys is reported as such. GitHub's Linux job ran those groups as two steps; they are now one step that runs the script under sudo. ci-local.sh takes --root-tests or FIPS_CI_ROOT_TESTS=1 alongside --baremetal and --slow-tests, and --rerun rejects both forms. The README section sits beside the known-defect lane, and the comments that said which runners run these tests now name the script. The held-SYN re-clamp and ingress fragmentation for paths under 1280 are ported rather than taken as written: on master the IPv6 adapter hands the node compressed datagrams and the node judges them in handle_datagram. - The fragmenter moves to src/ipv6tun/ipv6_frag.rs with its body and tests unchanged, listed as one of the adapter's decision modules. - outbound.rs gains can_split, split and reclamp, pure functions that rebuild a held datagram's packet, fragment it or clamp its SYN, and compress the result. mss.rs gains flow_ceiling, the per-flow MSS ceiling the TUN reader and the release-time re-clamp now share. - handle_datagram lets a datagram over the node-wide limit or an established session's path MTU carry on whole when it can be fragmented. The established send and the flush of held datagrams go through send_tun_packet, which sends a datagram whole or as fragments by the smaller of the node's own limit and the session's path MTU, and the flush clamps a held SYN again from the node's own path MTU map. - A Packet Too Big for a packet over 1280 on a path under 1280 reports 1280, both for a datagram the node refuses and for one the adapter answers itself. - The new node tests are ported to master's TUN taps and compressed held payloads. The two existing Packet Too Big tests that now use a Hop-by-Hop header give it a real length, since master's ICMPv6 builder does not answer a packet whose extension headers run past its end. The host-link tests of refusals send a packet with a Hop-by-Hop header where they mean a packet that is refused rather than fragmented, and one of them also checks that a fragmentable oversized packet to a key the node cannot resolve is told no route. The IPv6 adapter design document now says that on this structure the node decides fragmentation at its two refusal sites and splits a datagram where it sends it, that it clamps a held SYN again from its own path MTU map when it releases the datagrams it held, and that both apply to an app-owned TUN because the node holds and releases the datagrams of either path. It also names the functions an app-owned TUN's packets pass through on this structure, Handles::outbound and handle_datagram, and the MTU document says it is the ingress node that fragments.
Tutorials
If you have just installed FIPS, this is where to start. The tutorials below take you from a freshly-installed daemon to a node that:
- Has joined the public test mesh and can reach other nodes on it.
- Carries a stable identity that other operators can address.
- Discovers peers — and is discoverable — over Nostr.
- Hosts and consumes real services across the mesh.
Each tutorial is a complete, working session at the keyboard. You configure something, restart the daemon, watch it come up, and verify the result. The point is to build muscle memory, not to cover every option.
Read them in order. Each tutorial assumes the state the previous one left you in. If you skip ahead, the cross-references that lead you back may not match what you have on disk.
The new-user progression
| # | Tutorial | What you'll do |
|---|---|---|
| 1 | join-the-test-mesh.md | Add one public test peer to your config, watch the link come up, ping that peer and a second mesh node it routes you to. The starting point for everything else. |
| 2 | persistent-identity.md | Pin your daemon to a stable Nostr keypair so your address stops changing on every restart. Other operators can now add you to their peers: lists; the services you host get a fixed name. |
| 3 | resolve-peers-via-nostr.md | Stop hard-coding peer addresses. Drop the address line from your peer entry and let the daemon look up the current endpoint from public Nostr relays at dial time. |
| 4 | advertise-your-node.md | Publish your own UDP endpoint to Nostr so any operator who knows your npub can reach you, with a short final section on udp:nat best-effort hole-punching for nodes without a directly reachable UDP endpoint. |
| 5 | open-discovery.md | Switch to policy: open and let your peer list populate itself from the ambient fips-overlay-v1 namespace. Hands-off mesh participation. |
| 6 | reach-mesh-services.md | Drive ordinary IPv6 tools — ping6, nc, traceroute6, curl, ssh — at mesh nodes by <npub>.fips. Get a feel for the daemon's IPv6 adapter, which makes unmodified IPv6 software work over the mesh. |
| 7 | host-a-service.md | Bring up an HTTP server bound to fips0 so mesh nodes can reach it, with a deliberate exposure decision (mesh-only vs every interface), and the mesh firewall as a default-deny baseline. The peer ACL (a separate, transport-layer control over which npubs may peer with your node) is briefly mentioned alongside. |
| 8 | ground-up-mesh.md | Bring up a second deployment mode: two devices joined by Ethernet (or WiFi, or BLE) with no IP infrastructure between them. The mesh emerges from layer 2 up. Coexists with overlay peers — the same daemon can carry both. |
After tutorial 8 you have a fully participating mesh node that reaches services hosted by other mesh nodes and hosts services of its own, with identity, discovery, reachability, an explicit exposure policy, and an understanding of both deployment modes — overlay on top of existing IP, and ground-up where the mesh is the network.
There are also two side trips you can take:
-
ipv6-adapter-walkthrough.md — trace one
sshfrom DNS query through session setup to the far-side TUN, usingfipstopandfipsctlto watch each step. Optional, but if you like seeing how the pieces fit together, this is the doc that shows you. Take it any time after tutorial 1. -
native-api-walkthrough.md — write a program against the experimental native datagram API, addressing a peer by public key and port with no IPv6 emulation and no TUN. Runs two throwaway nodes on one machine, so it needs no mesh and no root, and you can take it without doing the tutorials first.
Advanced
These are not part of the new-user progression. They assume you have already worked through the tutorials above and now want to fold FIPS into a wider network deployment.
- deploy-fips-gateway.md — Stand up a
fips-gatewayon an OpenWrt access point so unmodified LAN hosts can reach<npub>.fipsdestinations through a DNS- allocated virtual IPv6 pool and kernel nftables NAT, with no per-host FIPS install. Also walks through one inbound port forward exposing a LAN service to mesh peers. Aimed at operators bridging a LAN segment into the overlay from the edge router. For a non-OpenWrt host the same deployment is in ../how-to/deploy-gateway.md.
When to use the how-to guides instead
The tutorials here walk through one specific path each. The how-to guides under ../how-to/ are the operator recipes — alternative provisioning paths, less-common configurations, troubleshooting techniques. Once you have the shape of FIPS in your head from these tutorials, the how-tos are where you'll go to look up "how do I do X?" without being walked through the surrounding context.