mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-06 03:28:24 +00:00
Johnathan Corgan
40c67abbe6
Five files conflicted and each needed a different call, because the two lines had rewritten different halves of the same code. The handshake handler takes next's version whole. master's entire change there was three comment blocks and one widened debug_assert, and the assert names HandshakePhase::ReceivedMsg1, a variant next's XX rewrite does not have. Nothing semantic was dropped. The peer reaper takes master's: reap_peers_on_transport is new and its route_link_dead doc now describes both callers, which is true on this line too. The ethernet transport takes master's binder rewrite with next's wire format re-applied on top. The send path, the receive path and the frame tests merged to the 4-byte header on their own, but three sites are new in master's rewrite and had never seen it: the Binding default and both arms of the binder's MTU calculation still subtracted 3. The transports snapshot fixture moved with them, 1499 to 1496, and that single field was the whole diff. Beacons carry no pubkey here, so local_pubkey leaves the transport, its binder context and the node's transport construction with it. The changelog keeps both sides' entries, with master's Added subsection lifted back out of Changed where the merge had left it. Two tests do not come across. a_transient_msg2_failure_keeps_the_link_for_ the_retry and its restart-path sibling assert that the machine rests at ReceivedMsg1. This line's nearest state is SentMsg2, and it means something else: the inbound leg parks there awaiting msg3, where on the other line that phase was the last stop before promotion. Renaming it would produce a test that passes without exercising the deferral. The behaviour they guard did merge and sits in the transient arm of the msg2 send failure; what is missing is coverage shaped for this handshake, which is tracked separately. The two connected-socket tests did come across. Their helper took the responder's session straight after msg2, which is an IK assumption; it now runs msg3 as well. Both pass here and both go red when the clear is removed or made unconditional. The test-harness fixes arrive through master rather than as follow-ups here, so this line never carries the versions that failed: the interface-binding suite's veth naming, and the chaos veth restore, random streams, settle wait, netem restore and shared down-node set.
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-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 |