mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-09 00:04:54 +00:00
Johnathan Corgan
45a8a4cd9b
Forward-merge of 12 master commits past the previous merge (823b830, master @18019bb): dep-audit bumps (rand, clap, tun, rtnetlink, windows-service, plus the bump-safe lockfile batch), bloom-storm chaos scenario, control-socket resolver consolidation, gateway dns.listen default change, OpenWrt ipk README refresh, gateway tutorial review, Ethernet MTU rustdoc fix, dead session-variant drop, CHANGELOG prep. Conflict resolution: - CHANGELOG.md: both bullets kept under [Unreleased] / Fixed. Master's spanning-tree internal-path-propagation fix precedes next's tree-ancestry-test determinism entry and the responder-Disconnect XX-handshake entry. - src/protocol/session.rs: kept next's SessionSetup/SessionAck variants and rustdoc. Master's drop of those variants suits v0.3.0's FSP phase-byte dispatch but is undone by next's v0.4.0 wire format, which retains the variants and uses the inner msg_type byte for handshake identification. - src/transport/ethernet/mod.rs: kept next's "interface MTU - 4" comment. Master corrected the v0.3.0 3-byte rustdoc; next redesigned the framing to a 4-byte header (type/flags/length) for shared-media beacons, so master's correction does not apply to next's format. Auto-merged cleanly: Cargo.toml (next's 0.4.0-dev + the new dep pins from master), Cargo.lock, all gateway docs, docs/reference/configuration.md, packaging files, .github/workflows/ci.yml, testing/chaos/sim/* and testing/ci-local.sh (bloom-storm additions), src/config/*. Local verification: cargo build --release, cargo test (1252 passed, 4 ignored), cargo clippy -D warnings, cargo fmt --check all green.
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 |
| 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 |
| diagnose-mtu-issues.md | Triage MTU-shaped failures and rule out their imposters (bufferbloat, transport saturation) |