Johnathan Corgan
f4b2632646
On upgrade the package reloaded nothing: fips-firewall.service kept the ruleset loaded at boot, so a changed /etc/fips/fips.nft did not take effect until the next reboot or a manual restart, and a restart runs ExecStop, which deletes the fips table and leaves the mesh interface unfiltered until ExecStart loads it again. fips-firewall.service, in both the Debian and the plain systemd unit, gains an ExecReload that runs the same nft -f. The file adds and then flushes the table before defining it, so one run replaces the ruleset in a single transaction. postinst now runs try-reload-or-restart on the unit before it starts the daemon. That acts only when the unit is already active, so it never turns the firewall on for a host that has not opted in, and a reload that fails leaves the previous ruleset in place, so it is reported and the upgrade goes on. The upgrade scenario gains a host with the firewall enabled. Its newer package carries a ruleset with an extra named counter; after the upgrade the counter must be loaded, and an nft monitor running across the upgrade, proven to be recording first, must show no deletion of the fips table. The host that never opted in must still have the firewall inactive, disabled and its table absent.
FIPS Installation Guide
Quick Start
tar xzf fips-*-linux-*.tar.gz
cd fips-*-linux-*/
sudo ./install.sh
What Gets Installed
| File | Location |
|---|---|
| fips (daemon) | /usr/local/bin/fips |
| fipsctl (CLI) | /usr/local/bin/fipsctl |
| fipstop (TUI) | /usr/local/bin/fipstop |
| fips-gateway (LAN bridge) | /usr/local/bin/fips-gateway |
| Configuration | /etc/fips/fips.yaml |
| Identity key | /etc/fips/fips.key (auto-generated) |
| Public key | /etc/fips/fips.pub (auto-generated) |
| Hosts file | /etc/fips/hosts |
| Firewall baseline | /etc/fips/fips.nft |
| Firewall drop-in directory | /etc/fips/fips.d/ |
| Daemon unit | /etc/systemd/system/fips.service (enabled) |
| DNS routing unit | /etc/systemd/system/fips-dns.service (enabled) |
| Gateway unit | /etc/systemd/system/fips-gateway.service (NOT enabled) |
| Firewall unit | /etc/systemd/system/fips-firewall.service (NOT enabled) |
| DNS helpers | /usr/lib/fips/fips-dns-{setup,teardown} |
A system group fips is created for control socket access. By
default, only fips.service and fips-dns.service are enabled at
install time. fips-gateway.service and fips-firewall.service
are installed but require explicit operator opt-in (see the
sections below).
Post-Install Configuration
Edit /etc/fips/fips.yaml before starting the service.
1. Identity
By default, the node generates a new ephemeral identity on each start
for privacy. If the node's npub will be published for others to use as a
static peer, enable a stable identity by uncommenting persistent: true
in the identity section:
node:
identity:
persistent: true
On first start with persistence enabled, a keypair is auto-generated and saved:
/etc/fips/fips.key(mode 0600) — secret key/etc/fips/fips.pub(mode 0644) — public key (npub)
The same identity is reused on subsequent starts. Alternatively, set
node.identity.nsec to use a specific key.
2. Ethernet Transport
If using Ethernet for local mesh discovery, uncomment the ethernet section and set the interface name:
transports:
ethernet:
interface: "eth0"
listen: true
announce: true
auto_connect: true
accept_connections: true
3. Bluetooth Transport
BLE is compiled automatically on glibc Linux and Android; there is no cargo feature to enable. BlueZ must be installed and running:
sudo apt install bluez
sudo systemctl enable --now bluetooth
Add your service user to the bluetooth group, or run with
CAP_NET_ADMIN + CAP_NET_RAW capabilities.
Configure BLE in the transports section:
transports:
ble:
adapter: "hci0"
advertise: true
scan: true
auto_connect: true
accept_connections: true
4. Static Peers
For bootstrapping over UDP or TCP, add known peers:
peers:
- npub: "npub1..."
alias: "gateway"
addresses:
- transport: udp
addr: "test-us01.fips.network:2121" # IP or hostname (e.g., "peer.example.com:2121")
connect_policy: auto_connect
5. DNS Resolver
FIPS includes a DNS responder for .fips domain names that listens on
fips0 and on [::1]:5354. The fips-dns.service helper detects the
host's DNS routing system and configures it to forward .fips queries
to the responder. Backends tried in order:
- systemd
dns-delegatedrop-in (systemd >= 258, declarative) systemd-resolvedglobal drop-in via/etc/systemd/resolved.conf.d/systemd-resolvedper-linkresolvectl(legacy fallback)dnsmasq(standalone, drops a config in/etc/dnsmasq.d/)- NetworkManager with the
dnsmasqplugin
If none of the supported backends is detected, fips-dns-setup logs a
warning with manual instructions and exits cleanly. The daemon itself
keeps working; only the host's .fips resolution is left unwired.
The installer enables fips-dns.service automatically. To disable
or re-enable later:
sudo systemctl disable --now fips-dns.service # disable
sudo systemctl enable --now fips-dns.service # re-enable
6. Mesh-interface firewall baseline (optional)
fips.nft is a default-deny baseline for inbound traffic on the
fips0 mesh interface. It is shipped as /etc/fips/fips.nft (not
loaded by default) along with a disabled fips-firewall.service
unit. Enable it explicitly:
sudo systemctl enable --now fips-firewall.service
The baseline polices only fips0, leaving Docker, Tor, the host
firewall, and other interfaces untouched. Outbound from fips0 is
unrestricted; inbound is dropped except for replies to outbound
flows, ICMPv6 echo-request, and any operator drop-ins under
/etc/fips/fips.d/*.nft. Read the comments at the top of
/etc/fips/fips.nft for the full policy and how to add per-service
allow rules.
7. Outbound LAN gateway (optional)
fips-gateway bridges unmodified LAN hosts to .fips destinations
through a DNS-allocated virtual IPv6 pool and kernel nftables NAT.
The binary is installed at /usr/local/bin/fips-gateway and a
fips-gateway.service unit ships disabled by default.
To enable it, configure the gateway block in /etc/fips/fips.yaml,
then:
sudo systemctl enable --now fips-gateway.service
The unit Requires=fips.service, waits up to 30 seconds for fips0
to come up, and runs fips-gateway --config /etc/fips/fips.yaml.
Inbound port-forward rules can be added in the same gateway:
block.
Firewall Ports
| Port | Protocol | Purpose |
|---|---|---|
| 2121 | UDP | Peer-to-peer mesh traffic |
| 8443 | TCP | Inbound peer connections |
Service Management
The install ships four units. fips.service and fips-dns.service
are enabled at install time. fips-gateway.service and
fips-firewall.service are installed but disabled until the
operator opts in.
# Daemon
sudo systemctl start fips
sudo systemctl stop fips
sudo systemctl restart fips
# DNS routing helper
sudo systemctl restart fips-dns
# Optional services (opt-in)
sudo systemctl enable --now fips-firewall # mesh-interface nftables baseline
sudo systemctl enable --now fips-gateway # outbound LAN gateway
# View logs (any of the units above)
sudo journalctl -u fips -f
sudo journalctl -u fips-gateway -f
sudo journalctl -u fips-firewall -f
# Switch to debug logging
sudo systemctl set-environment RUST_LOG=debug
sudo systemctl restart fips
Monitoring
# Quick status
fipsctl show status
# Interactive dashboard
fipstop
# Other queries
fipsctl show peers
fipsctl show links
fipsctl show sessions
fipsctl show routing
fipsctl show transports
Non-Root Access to fipsctl/fipstop
Add your user to the fips group:
sudo usermod -aG fips $USER
Log out and back in for the group change to take effect.
Uninstall
# Remove binaries and service, keep configuration
sudo ./uninstall.sh
# Remove everything including /etc/fips/ and the fips group
sudo ./uninstall.sh --purge