mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-30 19:46:15 +00:00
Johnathan Corgan
bf77ececad
The previous default configured systemd-resolved with `resolvectl dns fips0 [<fips0_addr>]:5354`, intended to bypass an Ubuntu 22 systemd 249 interface-scoping bug. That target collides with the daemon's mesh-interface filter on Linux: when an IPv6 packet's destination belongs to a non-loopback interface, the kernel attributes the packet to that interface in IPV6_PKTINFO (ipi6_ifindex == fips0) even though loopback delivery is used (tcpdump shows lo). The mesh-interface filter sees arrival_ifindex == mesh_ifindex and silently drops every query at trace level — invisible to operators at the default debug level. Net effect on stock deployments: every .fips query on systemd-resolved hosts was silently dropped. Daemon side ----------- - Default `dns.bind_addr` changes from "::" to "::1" (IPv6 loopback only). The mesh-interface filter is then defanged on the default path because loopback isn't reachable from mesh peers. The filter remains in place defensively for operators who explicitly bind "::" to expose a mesh-reachable responder. fips-dns-setup backend unification ---------------------------------- - New `try_global_drop_in` backend writes /etc/systemd/resolved.conf.d/fips.conf with DNS=[::1]:5354 and Domains=~fips. Inserted ahead of `try_resolvectl` in the dispatch chain. The standard loopback path has no interface scoping, so ipi6_ifindex reports lo and the filter passes. - All other backends now target [::1]:5354 to match the daemon's default IPv6-loopback bind: - try_dns_delegate writes DNS=[::1]:5354 - try_dnsmasq writes server=/fips/::1#5354 - try_nm_dnsmasq writes server=/fips/::1#5354 - Fixed dns-delegate file path: was /etc/systemd/dns-delegate/, must be /etc/systemd/dns-delegate.d/ (with .d suffix). systemd-resolved silently ignored the previous path. - fips-dns-teardown handles the new global-drop-in backend in cleanup. - The legacy resolvectl per-link backend stays as a fallback, documented to require careful daemon bind_addr coordination. fips-gateway upstream pairing ----------------------------- - gateway.dns.upstream default changes from 127.0.0.1:5354 to [::1]:5354 to match the daemon's default bind. Linux IPv6 sockets bound to explicit ::1 do not accept v4-mapped traffic, so the old default would have caused the gateway's startup DNS reachability probe to time out and systemd to restart-loop the service. - Operators who set a non-default daemon `dns.bind_addr` must also set `gateway.dns.upstream` to match — documented inline. Documentation ------------- - packaging/common/fips.yaml and packaging/openwrt-ipk fips.yaml examples updated; rationale for the bind_addr choice and the daemon/gateway pairing recorded inline. Test coverage ------------- - testing/dns-resolver/test.sh: real-fipsd end-to-end scenario added. Builds fipsd in a Debian 12 builder image (cached), runs the daemon with a real TUN in a privileged container, configures DNS via the setup script, and asserts `dig @127.0.0.53 AAAA <npub>.fips` returns AAAA. Refactored as a parameterized helper running across Debian 12/13 and Ubuntu 22/24/26 (5 e2e scenarios). Backend-aware assertions: on systemd >= 258 the expected backend is dns-delegate; on older systemd it's global-drop-in. Strict content checks fail CI on any [::1]:5354 drift. fips-gateway also exercised in the debian12 scenario to lock the gateway-upstream pairing. Renamed all "fipsd" references to "fips" (project convention). - testing/deb-install/ (new harness): builds the actual .deb via cargo-deb in a Debian 12 builder image (cached), installs via apt across each target distro, verifies maintainer scripts, conffile placement, binary placement, and end-to-end .fips resolution after start. Also exercises fips-gateway against the installed daemon to verify the gateway/daemon default pairing on a real .deb path. - This is the test layer that was missing — the previous harness only verified config files were written, never that queries reached the daemon. Verified: dns-resolver 78/78 assertions, deb-install 55/55 assertions across all 5 distros (debian:12, debian:trixie, ubuntu:22.04, ubuntu:24.04, ubuntu:26.04).
FIPS OpenWrt Package
This directory is an OpenWrt feed package that builds and installs FIPS on any
OpenWrt 22.03+ router via the standard opkg package system.
For ad-hoc deployment without the build system, see
deploy/native/ instead.
Package contents
| Installed path | Purpose |
|---|---|
/usr/bin/fips |
Mesh daemon |
/usr/bin/fipsctl |
CLI control tool (fipsctl peers, fipsctl links, …) |
/usr/bin/fipstop |
Live TUI dashboard |
/etc/init.d/fips |
procd service (auto-start, crash respawn) |
/etc/fips/fips.yaml |
Node configuration (edit before first start) |
/etc/fips/firewall.sh |
Firewall helper — accepts traffic on fips0 |
/etc/dnsmasq.d/fips.conf |
Forwards .fips DNS queries to the daemon |
/etc/sysctl.d/fips-bridge.conf |
br_netfilter settings for Ethernet transport |
/etc/hotplug.d/net/99-fips |
Applies firewall rules when fips0 comes up |
/etc/uci-defaults/90-fips-setup |
First-boot kernel module and firewall setup |
/lib/upgrade/keep.d/fips |
Preserves /etc/fips/ across sysupgrade |
Requirements
Build host
| Requirement | Notes |
|---|---|
| OpenWrt SDK 22.03+ | Older versions lack fw4 / nftables support |
| Rust host toolchain | Enable in make menuconfig → Advanced → Rust, or install rustup |
| Rust target for your router | Added automatically by the Makefile via rustup target add |
Router
| Requirement | Notes |
|---|---|
kmod-tun |
Required for fips0 TUN interface |
kmod-br-netfilter |
Required for Ethernet transport on bridge member ports |
Both kernel modules are listed as package dependencies (DEPENDS) and will be
installed automatically by opkg.
Target architectures
The Makefile maps the OpenWrt ARCH variable to the correct Rust musl target:
OpenWrt ARCH |
Rust target |
|---|---|
aarch64 |
aarch64-unknown-linux-musl |
x86_64 |
x86_64-unknown-linux-musl |
mipsel |
mipsel-unknown-linux-musl |
mips |
mips-unknown-linux-musl |
arm |
arm-unknown-linux-musleabihf |
To add a missing architecture, add an ifeq block in Makefile mapping the
OpenWrt ARCH value to the Rust target triple.
Building with the OpenWrt SDK
1. Obtain the SDK
Download the SDK for your router's target from downloads.openwrt.org and extract it.
2. Add this package
Copy or symlink this directory into the SDK's package/ tree:
# From inside the SDK root:
ln -s /path/to/fips/packaging/openwrt package/fips
Or add the FIPS repository as a feed in feeds.conf:
src-git-full fips https://github.com/jmcorgan/fips.git
Then update and install feeds:
./scripts/feeds update fips
./scripts/feeds install -a -p fips
3. Build
make package/fips/compile V=s
The resulting .ipk is placed in bin/packages/<arch>/.
4. Pin the source version
For reproducible production builds, replace PKG_SOURCE_VERSION:=master in
Makefile with a specific commit SHA and set PKG_MIRROR_HASH to the correct
hash (or keep skip for development):
PKG_SOURCE_VERSION:=bf117dfabc123... # full 40-char SHA
PKG_MIRROR_HASH:=skip
Installing on the router
scp bin/packages/<arch>/fips_0.1.0-1_<arch>.ipk root@192.168.1.1:/tmp/
ssh root@192.168.1.1 opkg install /tmp/fips_0.1.0-1_<arch>.ipk
First-time configuration
Edit /etc/fips/fips.yaml on the router before starting the daemon:
ssh root@192.168.1.1
vi /etc/fips/fips.yaml
The default config enables:
- Persistent identity (key generated on first start, saved to
/etc/fips/fips.key) - TUN interface
fips0 - DNS responder on
127.0.0.1:5354 - UDP transport on
0.0.0.0:2121
For Ethernet transport, uncomment the ethernet: section and set the correct
physical interface names for your router. Always use physical port names
(eth0, eth1), never bridge names (br-lan). See
deploy/native/README.md for details.
Service management
/etc/init.d/fips start
/etc/init.d/fips stop
/etc/init.d/fips restart
/etc/init.d/fips enable # start at boot (already enabled by opkg postinstall)
/etc/init.d/fips disable
Inspection and logs
# Peer table
fipsctl peers
# Active sessions
fipsctl sessions
# Transport links
fipsctl links
# Live TUI dashboard
fipstop
# Daemon logs (OpenWrt syslog)
logread | grep fips
Upgrading
Install the new .ipk over the existing one:
opkg install --force-reinstall fips_<new-version>_<arch>.ipk
The config in /etc/fips/fips.yaml and the identity key /etc/fips/fips.key
are preserved by opkg (the yaml is installed as a conffile; the key is not a
package file). Both survive sysupgrade via /lib/upgrade/keep.d/fips.