mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-30 07:37:36 +00:00
Johnathan Corgan
37196604d7
Move the staged changelog entries under a 0.5.3 heading dated 2026-10-16, marked provisional in the heading itself, and leave an empty Unreleased section above it. The topic groups follow the order the 0.5.2 section uses, and fixes that described one mechanism in several entries now read as one: the gateway's virtual IP handling, the macOS sending threads, the transport counters, the forged and unreadable SessionMsg3 and SessionSetup cases, and the same-epoch msg1 handling. No entry's detail was dropped. Add the release notes and mirror them byte for byte to RELEASE-NOTES.md, with every link absolute and each paragraph on one line. They lead with who should upgrade and what to do first: the SSH rule and gateway forwarding before an OpenWrt upgrade, the farthest-first order for routers reached over an 802.11s mesh, the Windows installer's stop on a key left in \etc\fips, the refusal of a config that configures nothing, the gateway's LAN-only translation and pool checks, and the changed fips.nft, including what the systemd tarball does with an edited copy. The upgrade steps say to restart fips after the network reload on an OpenWrt mesh or gateway router, since a running daemon does not form links over a recreated interface, and give the upgrade, reload and restart as one detached command for a router reached over SSH. The FreeBSD restart after the package upgrade is required, because pkg ends the daemon the package starts. On Windows, a key moved out of \etc\fips needs node.identity.persistent: true beside it and the old fips.yaml deleted, and a service registered by hand is checked with sc.exe qc first. On Debian, the steps cover each answer at the fips.nft prompt, an upgrade run without a terminal, and masking fips-dns on a host that renamed the TUN, which fips-dns does not support. A gateway on a VLAN device on a bridge is affected only when br_netfilter passes bridged IPv6 to the firewall, and only for clients whose traffic enters the bridge untagged; the notes say how to check and what the workaround costs, and that hosts off gateway.lan_interface lose .fips access. They state the wire-format comparison and what it does not cover, the limits that remain, the advisories accepted with the release including RUSTSEC-2024-0449, that no crate was added to the lockfile, the fips-mesh crate name and how a dependent names it, what was measured and what was not, and the contributors. The README's status badge, release-notes link and status paragraphs follow the release, without naming a branch. Correct documentation that no longer matches the release: - The fips and configuration references say the Windows \etc\fips config probe is deprecated, that the daemon warns when it loads a config from there, and that from v0.6.0 the search no longer looks there. - Getting started no longer says there is no cargo install path, since the crate is published; it says cargo install fips-mesh installs only the binaries and is not how to install the daemon. - The reachability how-to names its probe placeholder as a substitution, and the gateway port-forward recipe marks its example mesh address as the one to replace. - The mesh firewall how-to says the systemd tarball keeps an edited fips.nft and writes the new one as fips.nft.template. - The gateway design document and the configuration reference state the bridge netfilter condition under which a VLAN device on a bridge does not serve its clients. - The FreeBSD package README no longer says the package restarts the services on upgrade, and says to restart them by hand. - The OpenWrt package README's mesh upgrade order adds the fips restart after the reload, as a detached command.
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 |