mirror of
https://github.com/jmcorgan/fips.git
synced 2026-09-14 00:45:08 +00:00
ArjenandJohnathan Corgan
40b24cc9df
The mesh0/mesh1 and ap0/ap1 Ethernet transports shipped commented out, and fips-mesh-setup / fips-ap-setup awk-toggled the comment prefix in fips.yaml when they created or removed an interface. That existed for one reason: a transport whose interface was missing at startup was skipped and never retried, so a stock install that never ran the helpers would have logged a bind warning every boot. The daemon now waits for the interface and binds it when it appears, so the toggling has nothing left to protect. The blocks ship enabled with optional: true — which is the honest statement about a radio the router may never configure — and the helpers create the interface and stop there. No config rewrite, and no "restart fips AFTER the interface is up" step anywhere in either procedure. phy0-sta0 (wwan) gets optional: true for the same reason: it only exists while a radio is in station mode. eth0 and br-lan stay required, and the test pins that they do — marking the whole ethernet block optional would silence exactly the failures this policy exists to surface. With presence on IFF_UP rather than IFF_UP|IFF_RUNNING, that stays correct for a router with nothing plugged into its LAN ports: absence now means the netdev is gone or admin-down, a real fault, rather than an empty switch port. fips-ap-setup still edits node.rendezvous.lan, and that one does still need a restart: it is a config value, not an interface. The changelog entry gains an upgrade note. fips.yaml is a package conffile, so a router whose setup script had already uncommented a block keeps that block untouched and never receives the new key; with optional defaulting to false the block is required, and an absent interface there stays Degraded and errors once at ten seconds where the shipped file is silent.
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 |