fips/docs/how-to/enable-mesh-firewall.md

Enable the Mesh-Interface Firewall

FIPS ships a default-deny nftables baseline at /etc/fips/fips.nft that restricts inbound traffic on the fips0 mesh interface to conntrack replies and ICMPv6 echo. The baseline is not enabled by default — see ../design/fips-security.md for the threat model and the rationale behind keeping activation explicit. This guide covers the operator steps to load the baseline, extend it with per-host allowances, and inspect drops.

Activate the baseline

The package ships fips-firewall.service, a systemd oneshot that runs nft -f /etc/fips/fips.nft on start and removes the inet fips table on stop. To activate:

sudo systemctl enable --now fips-firewall.service

This loads the table now and arranges for it to load on every subsequent boot. To disable and tear it down:

sudo systemctl disable --now fips-firewall.service

To reload after editing /etc/fips/fips.nft or adding a drop-in under /etc/fips/fips.d/:

sudo systemctl reload-or-restart fips-firewall.service

The file is idempotent — it begins with add table inet fips; flush table inet fips; so re-running it replaces the live ruleset atomically. Equivalently:

sudo nft -f /etc/fips/fips.nft

If you rename the TUN

The baseline polices one interface, named by the define fips_if line near the top of /etc/fips/fips.nft:

define fips_if = "fips0"

Traffic arriving on any other interface returns from the chain unfiltered. The shipped value matches the default tun.name. If you set tun.name in fips.yaml to another name, change fips_if to the same name and reload:

sudo systemctl reload-or-restart fips-firewall.service

Until you do, the baseline filters nothing on the TUN, every listener on it is reachable from the mesh, and the forward chain returns every port-forwarded connection unrestricted. The daemon checks this when it brings the TUN up and logs a warning naming both interfaces, and fipstop's listening panel shows the "all listeners exposed" banner.

Because /etc/fips/fips.nft is a configuration file, an upgrade that changes it while you have edited it asks whether to keep your version (dpkg) or installs the new one beside yours (.pacnew on Arch). The systemd tarball's install.sh never replaces an existing file and writes the new one as /etc/fips/fips.nft.template. Keep your file and carry over any change you want from the new one.

Gateway port forwards

The baseline's inbound chain polices traffic addressed to this host (the input hook). A fips-gateway port forward rewrites the destination to a LAN host, so its traffic is forwarded and never reaches that chain or the fips.d/*.nft drop-ins. The baseline's second chain, forward, sees it instead. It accepts port-forwarded connections from the mesh unless a drop-in under /etc/fips/fips.d/forward/ refuses them, so with no such drop-in every port forward is open to the mesh. To restrict one, see Compose with the mesh firewall.

Folding the baseline into the host's main nftables

If you prefer to load the baseline from your existing /etc/nftables.conf rather than via the systemd unit, include it directly:

# in /etc/nftables.conf
include "/etc/fips/fips.nft"

In that case do not enable fips-firewall.service — the host's main nftables setup owns the loading. The two paths are mutually exclusive.

Extend with per-host allowances via drop-ins

The baseline drops everything inbound on fips0 except conntrack replies and ICMPv6 echo. To open specific services to specific mesh nodes, drop a file into /etc/fips/fips.d/ ending in .nft. Each file is included inline into the inbound chain at the marked point and may contain any nftables rule lines valid in that context.

Reload after editing:

sudo systemctl reload-or-restart fips-firewall.service
# or:  sudo nft -f /etc/fips/fips.nft

Allow inbound SSH from a specific mesh node

# /etc/fips/fips.d/ssh-from-bastion.nft
ip6 saddr fd97:1234:5678:9abc:def0:1234:5678:9abc tcp dport 22 accept

The source filter is the node's mesh address. To find a node's mesh address, look in their fips.pub (which contains the npub) and derive the address from it (only the leading fd byte is fixed; the other 15 come from the node's key), or query the running daemon:

fipsctl show identity-cache
fipsctl show peers

Allow inbound DNS broadly

Some services need to be reachable from any mesh node (a public DNS resolver, a public bootstrap node):

# /etc/fips/fips.d/dns-public.nft
udp dport 53 accept
tcp dport 53 accept

Omit the source filter only when the service is intended to be universally reachable on the mesh. The baseline's purpose is to make "universally reachable" an explicit decision rather than the default.

Multiple nodes, one service

# /etc/fips/fips.d/git-from-trusted.nft
ip6 saddr {
    fd97:1111:2222:3333:4444:5555:6666:7777,
    fd97:8888:9999:aaaa:bbbb:cccc:dddd:eeee
} tcp dport 9418 accept

Set syntax keeps multi-node rules readable and is more efficient than a chain of individual rules.

Verify with fipstop

fipstop's Node tab carries a Listening on fips0 panel (right-half of the Traffic block) that pairs each local IPv6 listener with its current baseline-filter classification. After adding or editing a drop-in and reloading, this is the fastest way to confirm the rule landed correctly without manually parsing nft list table inet fips.

Panel state	Reading
Service row in default White with OPEN in the State column	The chain has a canonical, unrestricted accept rule for this (proto, port). The service is reachable from any mesh node.
Service row in DarkGray with filt	No matching accept rule; the chain falls through to counter drop. The service is not reachable from the mesh.
Service row in DarkGray with filt?	A rule references the port but uses matchers the panel cannot fully decompose (saddr filter, jump, daddr filter). The intent is operator-defined; inspect with sudo nft list table inet fips to see the actual rule.
Yellow banner above the panel: "fips-firewall.service inactive — all listeners exposed"	The inet fips table is not loaded, or it is loaded but does not police the TUN (its fips_if names another interface, or its scoping rule has a shape the panel cannot read; see If you rename the TUN). Every listener is mesh-reachable (subject only to whatever ACL you have at the peer layer).

A common workflow when extending the baseline is to keep fipstop open on the Node tab in one terminal while editing /etc/fips/fips.d/ in another. After each sudo systemctl reload-or-restart fips-firewall.service, the panel re-classifies on the next poll tick and the affected row's State column flips. A row staying filt after you expected OPEN usually means the drop-in failed to load (syntax error in any file under /etc/fips/fips.d/ aborts the whole reload) or carries a saddr filter that triggers filt? rather than OPEN.

The classifier is conservative: it recognizes only the canonical unrestricted shapes (tcp dport N accept, udp dport N accept, dport { ... } accept, dport A-B accept). Source-restricted accepts intentionally render as filt? rather than OPEN — the panel is a security screen, and any rule that varies by source is an operator decision the panel will not silently bless as fully open.

Inspect drops

The baseline counter increments on every dropped packet. Inspect it:

sudo nft list table inet fips

Look for the counter packets N bytes M drop line at the bottom of the inbound chain. A non-zero counter means mesh nodes are sending traffic that hits the default-deny — usually benign (probes, neighbor discovery) but occasionally a misconfigured drop-in.

To see which packets are being dropped, uncomment the log line near the bottom of /etc/fips/fips.nft:

log prefix "fips drop: " level info limit rate 10/minute

Reload:

sudo nft -f /etc/fips/fips.nft

Then tail the kernel log:

sudo journalctl -k -f -g "fips drop:"

The rate-limit prevents flooding the journal under sustained probing. Adjust the rate, log level, or prefix as needed for the situation. Re-comment the rule when you are done; production hosts do not need the log line on by default.

See also

• ../design/fips-security.md — threat model, baseline design, and coexistence with other firewalls
• ../reference/security.md — consolidated security reference