Johnathan Corgan
87f0678ce0
start_service switched dnsmasq's .fips forwarding to the gateway's port
before the gateway ran. A gateway that then failed, on a config it could
not parse or on a NAT or route error after binding, left every LAN
client's .fips lookups going to a port nothing held, until someone
started the gateway by hand; procd gives up respawning after five
failures and says nothing.
procd now runs the init script's supervise command, which starts the
gateway, switches dnsmasq to its port once the gateway's own process holds
a socket bound there, and switches it back to the daemon's port when the
gateway exits for any reason, passing procd's SIGTERM on so the gateway can
clean up. Ownership is checked by matching a socket inode for the port in
/proc/net/udp{,6} against the gateway's open descriptors, so a port held by
something else, such as an mDNS responder on 5353, is never mistaken for the
gateway. supervise records the gateway's pid in /var/run/fips-gateway.pid,
and an exiting instance skips the swap back only when the gateway named
there, the one procd started in its place, holds the port. Every change to
the dnsmasq entry is made under one lock, so a stopping and a starting
gateway cannot interleave. stop_service still swaps back as before. The
exit status is the gateway's, so procd's respawn behaves as it did.
procd sends SIGTERM to the supervise shell and, five seconds later, SIGKILL
to that shell alone, so a gateway slow to stop would outlive it, holding its
port. supervise kills the gateway three seconds after passing the SIGTERM
on, and stops its watcher as soon as the gateway is gone.
A new scenario runs the command start_service hands procd against stub
gateways that hold their socket themselves and exit before binding, fail
after binding, are stopped by SIGTERM, or ignore it, against a port taken by
another process, and against a swap back with a process other than the
successor holding the port, and checks dnsmasq ends on the daemon's port
each time.
FIPS Packaging
This directory contains packaging for all supported target platforms.
Most build outputs go to deploy/ at the project root; make ipk
and make apk write to dist/ instead.
Quick Start
make deb # Debian/Ubuntu .deb (built in the pinned container)
make tarball # systemd install tarball
make ipk # OpenWrt .ipk (opkg, OpenWrt 24.x and earlier)
make apk # OpenWrt .apk (apk-tools, mandatory on OpenWrt 25+)
make aur # Arch Linux AUR package (fips-git, local build + namcap)
make pkg # macOS .pkg installer
make freebsd # FreeBSD .pkg package (on FreeBSD; use gmake)
make zip # Windows .zip package
make all # deb + tarball (default)
The two Debian build paths
make deb builds in a container pinned to the oldest supported
distribution, named with the glibc floor in
build-floor.env, and checks the package it produced
against that floor before handing it back. Its only host prerequisite is
docker: the toolchain and the build dependencies live in the image. This
is the path the release workflow, the integration suite and the internal
builder all take, so a package that passes locally is built the way the
shipped one is.
make deb-host is the old path. It builds on the host, at whatever glibc
the host has, and it is checked against nothing. Use it for local
iteration only. A package built on a current distribution records a
version dependency that the loader refuses on Debian 12 and Ubuntu 22.04,
which is what shipped in every Linux artifact from v0.3.0 through v0.5.0,
so it must not produce anything anyone else installs.
Build Prerequisites
The prerequisites below apply to the host-build targets. make deb needs
docker and nothing else.
These targets build FIPS from source, so the host needs a build
environment in addition to a Rust toolchain (the version pinned in
rust-toolchain.toml is auto-installed by rustup).
On Linux, libclang is required: the LAN gateway's nftables
bindings are generated by bindgen at build time, which needs
libclang.so on the build host. Without it the build fails inside the
rustables crate with an "Unable to find libclang" error.
sudo apt install libclang-dev # Debian / Ubuntu
This is a build-time prerequisite only — it is not a runtime
dependency, so hosts installing a pre-built .deb do not need it.
BLE is not optional, and it is not universal either. build.rs sets
ble_available for glibc Linux or Android, which is the set of
platforms with a concrete backend: the transport is absent from musl
Linux, macOS, FreeBSD and Windows builds entirely. On glibc Linux
libdbus-1-dev and pkg-config are hard build prerequisites: there is
no probe that skips BLE when they are missing. The BlueZ daemon is a
runtime dependency and is not needed to build.
Directory Structure
packaging/
aur/ Arch Linux AUR packaging (PKGBUILD, supporting files)
common/ Shared assets (default config, hosts file)
debian/ Debian/Ubuntu .deb packaging via cargo-deb
freebsd/ FreeBSD .pkg packaging via pkg-create(8)
macos/ macOS .pkg installer via pkgbuild
nixos/ NixOS flake module (services.fips.*)
systemd/ Generic Linux systemd tarball packaging
openwrt-ipk/ OpenWrt .ipk packaging via cargo-zigbuild (opkg)
openwrt-apk/ OpenWrt .apk packaging via cargo-zigbuild + apk mkpkg
windows/ Windows .zip package with service scripts
Formats
Debian/Ubuntu (.deb)
Built with cargo-deb. Installs
fips, fipsctl, fipstop, and fips-gateway to /usr/bin/, ships
the fips, fips-dns, fips-firewall, and fips-gateway systemd
units, and enables the fips and fips-dns services.
The default configuration ships as an example at
/usr/share/fips/fips.yaml.example and is not a dpkg conf-file.
(It is deliberately not under /usr/share/doc, which minimal and
container installs path-exclude, since the postinst reads it at install
time.)
On install, postinst seeds /etc/fips/fips.yaml (mode 600) from the
example only if it does not already exist, so a configuration that
was rendered by configuration management or edited by an operator is
never prompted for or clobbered on upgrade. To reset to defaults, remove
/etc/fips/fips.yaml and reinstall, or copy the example back manually.
# Build
make deb
# Install
sudo apt install ./deploy/fips_<version>_<arch>.deb
# Remove (preserves config and keys)
sudo dpkg -r fips
# Purge (removes config and identity keys)
sudo dpkg -P fips
systemd Tarball
A self-contained tarball with binaries and an install.sh script for
any systemd-based Linux distribution.
# Build
make tarball
# Install (on target host)
tar -xzf deploy/fips-<version>-linux-<arch>.tar.gz
sudo ./fips-<version>-linux-<arch>/install.sh
See systemd/README.install.md for full installation and configuration instructions.
OpenWrt (.ipk, opkg — OpenWrt 24.x and earlier)
Cross-compiled with cargo-zigbuild and assembled as a standard .ipk
archive. The build script accepts aarch64, mipsel, mips, arm and
x86_64; releases publish aarch64 and x86_64. The MIPS targets are
not built: 32-bit MIPS has no 64-bit atomics, which fips and
nostr-relay-pool both use (see the comment in
.github/workflows/package-openwrt.yml).
# Build (default: aarch64)
make ipk
# Build for a specific architecture
bash packaging/openwrt-ipk/build-ipk.sh --arch x86_64
See openwrt-ipk/README.md for router-specific installation instructions.
OpenWrt (.apk, apk-tools — mandatory on OpenWrt 25+)
OpenWrt 25 makes apk-tools the mandatory package manager (it is opt-in on
24.10). Same SDK-free approach
(cargo-zigbuild), but the .apk container is assembled by apk mkpkg
rather than hand-rolled, so the build additionally needs an apk-tools v3
apk binary built from source. The installed-filesystem payload is shared
with the .ipk package.
# Build (default: aarch64; also x86_64)
make apk
# Build for a specific architecture
bash packaging/openwrt-apk/build-apk.sh --arch x86_64
Packages are unsigned; install with apk add --allow-untrusted. See
openwrt-apk/README.md for building apk-tools and
router-specific installation.
macOS (.pkg)
Built with pkgbuild (included with Xcode command-line tools). Installs
binaries to /usr/local/bin/, config to /usr/local/etc/fips/, sets up
the /etc/resolver/fips DNS resolver for .fips domains, and loads a
launchd daemon. The TUN device is named utun<N> (kernel-assigned)
rather than fips0.
# Build
make pkg
# Install
sudo installer -pkg deploy/fips-<version>-macos-<arch>.pkg -target /
# Remove
sudo packaging/macos/uninstall.sh
FreeBSD (.pkg)
Built natively on a FreeBSD host with pkg create. Ships fips,
fipsctl, and fipstop (fips-gateway is excluded — its NAT backend
is nftables, Linux-only), rc.d services, and .fips DNS integration
for local_unbound, unbound, or dnsmasq. Config installs
sample-style under /usr/local/etc/fips/ (edits survive upgrades).
# Build (on FreeBSD; this Makefile needs GNU make — pkg install gmake)
gmake freebsd
# or directly, no gmake needed:
./packaging/freebsd/build-pkg.sh
# Install
pkg add ./deploy/fips-<version>-freebsd-<arch>.pkg
sysrc fips_enable=YES fips_dns_enable=YES
service fips start
service fips_dns start
See freebsd/README.md for host resolver setup and field-tested caveats.
Windows (.zip)
A ZIP archive containing binaries, default config, and PowerShell service helper scripts. Requires the wintun driver for TUN support.
# Build
make zip
# Or directly
powershell -File packaging/windows/build-zip.ps1
# Extract and install as service (requires Administrator)
Expand-Archive deploy\fips-<version>-windows-x86_64.zip -DestinationPath fips
cd fips
powershell -ExecutionPolicy Bypass -File install-service.ps1
# Uninstall (preserves config)
powershell -ExecutionPolicy Bypass -File uninstall-service.ps1
# Uninstall and remove config
powershell -ExecutionPolicy Bypass -File uninstall-service.ps1 -RemoveAll
Arch Linux (AUR)
Two AUR packages are maintained: fips (release, builds from tagged
tarball) and fips-git (development, builds from latest git master).
# Build and validate locally (git variant)
make aur
# Install from AUR
yay -S fips-git # development build from master
yay -S fips # release build from latest tag
See aur/README.md for AUR publication instructions and maintainer guide.
Nix / NixOS (flake)
A flake at the project root builds all four binaries
(fips, fipsctl, fips-gateway, fipstop) from source. It pins the
exact toolchain from rust-toolchain.toml via
fenix and wires up the
build-time native dependencies (libclang for bindgen, plus dbus
and pkg-config for BLE), so it needs no system setup beyond Nix with
flakes enabled.
nix build .#fips # build the package (all four binaries)
nix run .#fips -- --help # run a binary directly
nix run .#fipsctl -- show status
nix develop # dev shell with the pinned toolchain + cargo-edit
nix flake check # build + validate the flake
The flake also exposes:
overlays.default— addspkgs.fipsto nixpkgsnixosModules.default— a NixOS module (packaging/nixos/) that providesservices.fips.enableand runs the daemon as a systemd service
As a package only (no service management):
environment.systemPackages = [ fips.packages.${system}.default ];
As a managed NixOS service (recommended — starts on boot, journalctl logs):
# flake.nix
{
inputs.fips = {
url = "github:jmcorgan/fips";
inputs.nixpkgs.follows = "nixpkgs";
};
outputs = { self, nixpkgs, fips, ... }@inputs: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
specialArgs = { inherit inputs; };
modules = [
./configuration.nix
fips.nixosModules.default
{ services.fips.enable = true; }
];
};
};
}
See packaging/nixos/README.md for the full option
reference (services.fips.enable, .package, .configFile,
.openFirewall).
Shared Assets
common/ contains assets used across packaging formats:
fips.yaml— default configuration (ephemeral identity, UDP/TCP/TUN/DNS)hosts— static hostname-to-npub mappings for.fipsDNS resolution