mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-29 23:27:37 +00:00
Johnathan Corgan
0c52763f5f
The packaged mesh firewall had one chain, on the input hook. A fips-gateway port forward is a DNAT in prerouting, so its traffic is routed through the forward hook and never met that chain or its fips.d drop-ins. With the firewall loaded, every mesh node that could reach the gateway reached every forward, and the only way to restrict one was a separate table loaded by hand, which no test exercised. fips.nft now has a second chain in the inet fips table, on the forward hook. It returns for traffic not arriving on the mesh interface, accepts established and related packets, includes drop-ins from /etc/fips/fips.d/forward/*.nft, and then accepts the remaining port-forwarded connections with a counter. Forwards stay open to the mesh by default, so nothing changes on upgrade; a forward is restricted by a drop-in that accepts the allowed mesh addresses for its target address and port and drops the rest. A missing forward/ directory is fine. The static gateway suite gains a phase that loads the tree's fips.nft on the gateway with the drop-in taken from the deployment how-to, and checks that the allowed node reaches the TCP and UDP forwards, the other node is refused on both with each refusal counted by its own drop rule, and a forward with no drop-in line stays open. A packaging test checks the chain's rules and their order on every target. The how-to, the firewall guides, the troubleshooting step, the design and reference documents and the hosting tutorial describe the new chain and drop-in directory in place of the hand-loaded table, and say what happens to a hand-loaded table or a kept, edited fips.nft.
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 |