mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-29 23:27:37 +00:00
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.
How-To Guides
Task-oriented, step-by-step recipes for operators with a specific goal in mind. Each guide assumes the reader already knows what FIPS is and wants to get a particular thing done — enable a feature, deploy a component, troubleshoot a class of problem.
How-to guides do not teach concepts (that is the role of design/) and do not enumerate options (that is the role of reference/). They take the reader along the shortest correct path from "I want to do X" to "X is done".
Available Guides
| Guide | Goal |
|---|---|
| enable-mesh-firewall.md | Activate the default-deny nftables baseline on fips0 |
| enable-nostr-discovery.md | Turn on Nostr-mediated discovery (3 capabilities — resolve, advertise, open — across 5 scenarios) |
| deploy-tor-onion.md | Run a Tor onion service for inbound FIPS connections |
| tune-udp-buffers.md | Set host sysctls so FIPS UDP sockets don't get clamped |
| tune-file-descriptors.md | Raise RLIMIT_NOFILE so a busy node doesn't exhaust file descriptors (EMFILE) as peer count grows |
| run-as-unprivileged-user.md | Run the daemon under a dedicated unprivileged service account (drops the default-root posture) |
| deploy-gateway.md | Manually deploy fips-gateway on a non-OpenWrt Linux host (LAN-to-mesh outbound + mesh-to-LAN inbound port-forwards). For the OpenWrt path, see the gateway tutorial. |
| troubleshoot-gateway.md | Diagnostic recipes for the gateway, organised by half (outbound, inbound, common) |
| persistent-identity.md | Provision a stable Nostr keypair so the node keeps the same npub across restarts |
| host-aliases.md | Use shortnames (test-us01.fips, my-laptop.fips) instead of full npubs by editing /etc/fips/hosts or setting peer aliases |
| set-up-bluetooth-peer.md | Configure a Bluetooth Low Energy peer link |
| set-up-80211s-mesh-backhaul.md | Link OpenWrt FIPS routers over an open 802.11s radio backhaul (FIPS provides encryption, authentication, and routing) |
| set-up-open-access-ssid.md | Broadcast the open !FIPS access SSID so phones and laptops roam onto the mesh (one ESS: save once, roam every FIPS router) |
| diagnose-reachability.md | Find out whether one node can reach another, by what route, and why not: fipsctl probe, peers versus sessions, rerolled identities, relay ACLs and .fips name resolution |
| diagnose-mtu-issues.md | Triage MTU-shaped failures and rule out their imposters (bufferbloat, transport saturation) |
| use-the-native-datagram-api.md | Enable the experimental native datagram API and write a program that sends and receives datagrams by pubkey and port (no IPv6 emulation, no TUN). Read the fips group warning first |
| write-a-native-api-client.md | Speak the native datagram API's line protocol directly from C, Python or Go, where there is no client library |
| serve-many-peers-on-one-thread.md | Handle every native API flow from one poll loop instead of a thread per peer |
| migrate-an-embedder-to-v0.6.md | Move code that uses the fips library crate to v0.6.0: each change that can stop it building, and what to do |