mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-09 08:14:42 +00:00
Johnathan Corgan
0fcf0f6f8f
The gateway is designed for systems already serving DHCP and DNS to a LAN segment (canonically an OpenWrt AP). On those systems port 53 is already taken by the existing resolver, so the prior `[::]:53` default conflicted with the gateway's intended deployment target out of the box. The OpenWrt ipk previously overrode this in its packaged config as a workaround; matching the source default to what the canonical deployment actually wants makes the override redundant and removes a foot-gun for fresh manual Linux-host installs. The redundant `dns.listen` line in `packaging/openwrt-ipk/files/etc/fips/fips.yaml` is dropped along with this change. Operators on a host without a pre-existing resolver on port 53 can opt back into the wildcard bind by setting `dns.listen: "[::]:53"` explicitly. The new default binds IPv6 loopback only — Linux IPv6 sockets bound to explicit `::1` do not accept v4-mapped traffic, so forwarders that reach the gateway over IPv4 loopback need to be pointed at an explicit IPv4 listen address instead. Touches the gateway config struct and its default-value test, the commented-out gateway example in the Debian common fips.yaml, the OpenWrt ipk config (override removed), the gateway reference / how-to / design / tutorial / troubleshoot docs, and a CHANGELOG entry under [Unreleased] -> Changed.
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) |