Boot fallback, flowtable devices that come and go, healthz, renames

The boot unit fails closed: if ruleset.nft doesn't load, it loads
ruleset-fallback.nft (render.Fallback), saved beside it from the same
configuration: nothing new in from external zones, established, the
ICMPv6 IPv6 needs and DHCPv6 replies let in, the inside left alone and
masqueraded, and the unit marked failed with a critical message.
housecarld replaces it when it applies; status, the dashboard and
/healthz say while it is in force. no_external_zone now also says the
fallback closes everything without an external zone.

The boot ruleset has no flowtable: nftables on Debian 13's kernel
refuses one naming a device that doesn't exist yet (ppp0 before PPPoE),
and with it the whole file. internal/linkwatch listens to rtnetlink link
messages; housecarld applies again when a flowtable device appears or
comes back as a new interface (by ifindex), under the engine's lock.
docs/flowtable.md: what it does, when to use it and when not, how.

GET /healthz reports firewall (applied, unconfigured, fallback,
missing), changes on probation and the machine's warnings, with 503
unless in force, read at most every five seconds.

Renaming a zone, set or service changes what names it in the same
change (one history entry, one undo); dynamic sets keep their names.
The importer keeps a chain's head in order: once a would-be built-in
stays a rule, the ones after it do too, so the maintainer's ICMPv6
accepts stay behind the invalid drop as written. hc settings set
--flowtable none empties the list.

make test (nft 1.1.3) and make e2e (242 checks, with VLAN
sub-interfaces, the fallback and the flowtable) pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/nft/nft.go

@@ -14,6 +14,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"net"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -209,6 +210,9 @@ type Table struct {
 	// Tables are all the machine's tables ("inet main"), when the whole
 	// ruleset was read.
 	Tables []string
+	// Fallback: the table is the boot fallback (render.Fallback), not a
+	// ruleset housecarld applied.
+	Fallback bool
 }
 
 // QuotaUsage is what the quotas used: kept across reloads, and saved in
@@ -306,6 +310,9 @@ func ParseTable(data []byte) (*Table, error) {
 				continue
 			}
 			mark, _, _ := strings.Cut(strings.TrimPrefix(r.Comment, "hc:"), " ")
+			if strings.HasPrefix(mark, render.FallbackMark+"-") {
+				t.Fallback = true
+			}
 			for _, e := range r.Expr {
 				var c struct {
 					Counter *Counter `json:"counter"`
@@ -411,6 +418,35 @@ type Firewall struct {
 	// restore is the quota usage saved before housecarld (or the machine)
 	// stopped, put back by the next apply.
 	restore *QuotaUsage
+	// flowDevs are the flowtable's devices in the ruleset in force, by
+	// name, with their interface index then (0: left out, missing).
+	flowDevs map[string]int
+}
+
+// ifIndex is an interface's index, 0 if it doesn't exist (tests change it).
+var ifIndex = func(name string) int {
+	if i, err := net.InterfaceByName(name); err == nil {
+		return i.Index
+	}
+	return 0
+}
+
+// FlowtableStale reports whether the flowtable in force no longer matches
+// the machine: a device of st's flowtable appeared, went, or came back as
+// a new interface (ppp0 after PPPoE reconnects; the kernel drops a
+// device from the flowtable when it goes). Applying again fixes it.
+func (f *Firewall) FlowtableStale(st *model.State) bool {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.flowDevs == nil {
+		return false
+	}
+	for _, d := range st.Settings.FlowtableDevices {
+		if ifIndex(d) != f.flowDevs[d] {
+			return true
+		}
+	}
+	return false
 }
 
 // RestoreQuotas has the next apply put this saved quota usage back where
@@ -482,6 +518,12 @@ func (f *Firewall) Apply(ctx context.Context, st *model.State) error {
 		return err
 	}
 	f.restore = nil
+	f.flowDevs = map[string]int{}
+	for _, d := range st.Settings.FlowtableDevices {
+		if opt.Interfaces == nil || opt.Interfaces[d] {
+			f.flowDevs[d] = ifIndex(d)
+		}
+	}
 	if f.base == nil {
 		f.base, f.since = map[string]Counter{}, time.Now()
 	}
@@ -496,20 +538,37 @@ func (f *Firewall) Apply(ctx context.Context, st *model.State) error {
 	return nil
 }
 
-// SaveBoot writes the ruleset of st for the boot unit, atomically.
+// SaveBoot writes the ruleset of st for the boot unit, and the fallback
+// it loads if that fails (FallbackFile), atomically. The boot ruleset has
+// no flowtable: it loads before the network comes up, when its devices
+// (ppp0, wg0) don't exist yet and nftables would refuse the whole file;
+// housecarld adds it once they do.
 func (f *Firewall) SaveBoot(st *model.State) error {
 	if f.BootFile == "" {
 		return nil
 	}
-	rs := render.Render(st, f.options())
-	tmp := f.BootFile + ".tmp"
 	if err := os.MkdirAll(filepath.Dir(f.BootFile), 0o750); err != nil {
 		return err
 	}
-	if err := os.WriteFile(tmp, []byte(rs.Text), 0o640); err != nil {
+	if err := writeAtomic(FallbackFile(f.BootFile), render.Fallback(st)); err != nil {
 		return err
 	}
-	return os.Rename(tmp, f.BootFile)
+	rs := render.Render(st, render.Options{Interfaces: map[string]bool{}})
+	return writeAtomic(f.BootFile, rs.Text)
+}
+
+// FallbackFile is where the fallback for a boot ruleset is saved:
+// ruleset.nft's is ruleset-fallback.nft beside it.
+func FallbackFile(boot string) string {
+	return strings.TrimSuffix(boot, ".nft") + "-fallback.nft"
+}
+
+func writeAtomic(path, text string) error {
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, []byte(text), 0o640); err != nil {
+		return err
+	}
+	return os.Rename(tmp, path)
 }
 
 // Table reads Housecarl's table back, with counters totalled since

internal/nft/nft_test.go

@@ -2,8 +2,10 @@ package nft
 
 import (
 	"context"
+	"fmt"
 	"os"
 	"os/exec"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -257,3 +259,109 @@ func TestDeviceCountsInContainer(t *testing.T) {
 		t.Errorf("after a reload: %+v", e)
 	}
 }
+
+// TestFlowtableStale: the flowtable in force goes stale when one of its
+// devices appears, goes, or comes back as a new interface.
+func TestFlowtableStale(t *testing.T) {
+	idx := map[string]int{"eth1": 3}
+	old := ifIndex
+	ifIndex = func(name string) int { return idx[name] }
+	t.Cleanup(func() { ifIndex = old })
+	exists := func() map[string]bool {
+		out := map[string]bool{}
+		for n, i := range idx {
+			out[n] = i > 0
+		}
+		return out
+	}
+	// "true" stands in for nft: every apply succeeds, and lists nothing.
+	fw := &Firewall{Runner: &Runner{Command: []string{"true"}}, Interfaces: exists}
+	st := model.NewState()
+	st.Settings.FlowtableDevices = []string{"ppp0", "eth1"}
+	if fw.FlowtableStale(st) {
+		t.Error("stale before anything was applied")
+	}
+	if err := fw.Apply(context.Background(), st); err != nil {
+		t.Fatal(err)
+	}
+	if fw.FlowtableStale(st) {
+		t.Error("stale right after applying")
+	}
+	idx["ppp0"] = 7 // PPPoE came up
+	if !fw.FlowtableStale(st) {
+		t.Error("ppp0 appeared, yet not stale")
+	}
+	fw.Apply(context.Background(), st)
+	idx["ppp0"] = 9 // and reconnected: a new interface by the same name
+	if !fw.FlowtableStale(st) {
+		t.Error("ppp0 came back as a new interface, yet not stale")
+	}
+	fw.Apply(context.Background(), st)
+	idx["eth9"] = 4 // not a flowtable device
+	if fw.FlowtableStale(st) {
+		t.Error("stale over an interface the flowtable doesn't use")
+	}
+}
+
+// TestBootInContainer: the boot ruleset loads although its flowtable
+// devices don't exist yet, the fallback loads and is recognised, and
+// housecarld's apply replaces it.
+func TestBootInContainer(t *testing.T) {
+	image := os.Getenv("HOUSECARL_NFT_IMAGE")
+	if image == "" {
+		t.Skip("HOUSECARL_NFT_IMAGE not set")
+	}
+	name := "housecarl-nft-boot-test"
+	exec.Command("docker", "rm", "-f", name).Run()
+	if out, err := exec.Command("docker", "run", "-d", "--name", name, "--cap-add", "NET_ADMIN", image, "sleep", "300").CombinedOutput(); err != nil {
+		t.Fatalf("starting the container: %v %s", err, out)
+	}
+	t.Cleanup(func() { exec.Command("docker", "rm", "-f", name).Run() })
+	nft := func(script string) error {
+		c := exec.Command("docker", "exec", "-i", name, "nft", "-f", "/dev/stdin")
+		c.Stdin = strings.NewReader(script)
+		if out, err := c.CombinedOutput(); err != nil {
+			return fmt.Errorf("%v: %s", err, out)
+		}
+		return nil
+	}
+	dir := t.TempDir()
+	// ppp0 exists when housecarld saves, but not at boot.
+	fw := &Firewall{Runner: &Runner{Command: []string{"docker", "exec", "-i", name, "nft"}}, BootFile: filepath.Join(dir, "ruleset.nft"),
+		Interfaces: func() map[string]bool { return map[string]bool{"ppp0": true, "eth0": true} }}
+	st := model.NewState()
+	st.Zones = []*model.Zone{{ID: 1, Name: "wan", Interfaces: []string{"ppp0"}, External: true}, {ID: 2, Name: "lan", Interfaces: []string{"eth0"}}}
+	st.SNATs = []*model.SourceNAT{{ID: 3, Match: model.Match{OutZones: []string{"wan"}}}}
+	st.Settings.FlowtableDevices = []string{"ppp0", "eth0"}
+	if err := fw.SaveBoot(st); err != nil {
+		t.Fatal(err)
+	}
+	boot, _ := os.ReadFile(fw.BootFile)
+	if strings.Contains(string(boot), "flowtable") {
+		t.Errorf("the boot ruleset has a flowtable:\n%s", boot)
+	}
+	fallback, err := os.ReadFile(filepath.Join(dir, "ruleset-fallback.nft"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := nft(string(boot)); err != nil {
+		t.Fatalf("the boot ruleset doesn't load: %v", err)
+	}
+	ctx := context.Background()
+	if tb, err := fw.Table(ctx); err != nil || tb.Fallback {
+		t.Errorf("after the boot ruleset: %+v %v", tb, err)
+	}
+	if err := nft(string(fallback)); err != nil {
+		t.Fatalf("the fallback doesn't load: %v", err)
+	}
+	if tb, err := fw.Table(ctx); err != nil || !tb.Fallback {
+		t.Errorf("the fallback isn't recognised: %+v %v", tb, err)
+	}
+	fw.Interfaces = func() map[string]bool { return map[string]bool{"eth0": true} }
+	if err := fw.Apply(ctx, st); err != nil {
+		t.Fatalf("apply over the fallback: %v", err)
+	}
+	if tb, err := fw.Table(ctx); err != nil || tb.Fallback {
+		t.Errorf("the fallback stayed after an apply: %+v %v", tb, err)
+	}
+}