Add changesets, bandwidth limits and quotas; generic examples

Changesets, as in Jarl: configuration changes are operations that can be staged in a changeset, checked as they are added (validation and nft -c), reviewed with the diff of the ruleset, and applied together as one history entry, then on probation like any change made over the network. The web UI collects edits for review by default (pending rows, a bar with Review and Apply now, a Changes page, a switch for live edits); hc stages with -C ID or HOUSECARL_CHANGESET (checked like JARL_CHANGESET) and has hc changeset create/list/show/diff/apply/discard/remove. Undo, import and takeover refuse a changeset. --dry-run shows the ruleset's diff. Bandwidth and quotas: rate limits in bytes, per source or destination; quotas per rule or per address that reset daily, weekly, monthly on a day, or by hand, with their usage carried across reloads, saved for reboots, shown by hc quotas and on the rules page, and reset with hc rule reset-quota. Rules that count traffic are checked before established connections are accepted (so they see every packet) and can't accept. Per-address limits group IPv6 by /64 by default (--group-v4/-v6). Per-source rate meters use update. The importer turns meters, byte rates and quotas into these fields. The examples in the web UI, hc's help and the docs use documentation addresses and generic names instead of the maintainer's network. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 11:18:54 +01:00
1 parent ebec2cfcca
commit 2880f7ddc9
@@ -196,6 +196,9 @@ type Table struct {
 	Counters map[string]Counter
 	// Elements by set name (both families together).
 	Elements map[string][]render.Element
+	// Quotas: the rules' quotas' used bytes (quota_r12), and the
+	// per-address quotas' entries by set (quota_r12_v4).
+	QuotaUsage
 	// Since is when the counters started (housecarld's first apply).
 	Since time.Time
 	// Tables are all the machine's tables ("inet main"), when the whole
@@ -203,6 +206,48 @@ type Table struct {
 	Tables []string
 }

+// QuotaUsage is what the quotas used: kept across reloads, and saved in
+// the database so a reboot doesn't reset it.
+type QuotaUsage struct {
+	Quotas    map[string]int64            `json:"quotas,omitempty"`
+	QuotaSets map[string][]render.Element `json:"quota_sets,omitempty"`
+}
+
+// merge takes the larger usage of each quota and entry from o (what was
+// saved before a reboot, when the kernel's count started again).
+func (u *QuotaUsage) merge(o *QuotaUsage) {
+	if o == nil {
+		return
+	}
+	if u.Quotas == nil {
+		u.Quotas = map[string]int64{}
+	}
+	if u.QuotaSets == nil {
+		u.QuotaSets = map[string][]render.Element{}
+	}
+	for k, v := range o.Quotas {
+		if v > u.Quotas[k] {
+			u.Quotas[k] = v
+		}
+	}
+	for set, es := range o.QuotaSets {
+		for _, e := range es {
+			found := false
+			for i := range u.QuotaSets[set] {
+				if u.QuotaSets[set][i].Addr == e.Addr {
+					found = true
+					if e.Used > u.QuotaSets[set][i].Used {
+						u.QuotaSets[set][i].Used = e.Used
+					}
+				}
+			}
+			if !found {
+				u.QuotaSets[set] = append(u.QuotaSets[set], e)
+			}
+		}
+	}
+}
+
 // Counter is packets and bytes.
 type Counter struct {
 	Packets uint64 `json:"packets"`
@@ -223,9 +268,25 @@ type jsonSet struct {
 	Elem []json.RawMessage `json:"elem"`
 }

+// jsonQuota is a quota's state: a named quota ({"bytes", "used"}, in
+// bytes) or one in an element ({"val", "val_unit", "used", "used_unit"}).
+type jsonQuota struct {
+	Name     string `json:"name"`
+	Used     int64  `json:"used"`
+	UsedUnit string `json:"used_unit"`
+}
+
+func (q jsonQuota) bytes() int64 {
+	if m, ok := model.ByteUnits[q.UsedUnit]; ok {
+		return q.Used * m
+	}
+	return q.Used
+}
+
 // ParseTable reads `nft -j list table inet housecarl`.
 func ParseTable(data []byte) (*Table, error) {
-	t := &Table{Counters: map[string]Counter{}, Elements: map[string][]render.Element{}}
+	t := &Table{Counters: map[string]Counter{}, Elements: map[string][]render.Element{},
+		QuotaUsage: QuotaUsage{Quotas: map[string]int64{}, QuotaSets: map[string][]render.Element{}}}
 	if len(data) == 0 {
 		return t, nil
 	}
@@ -252,11 +313,31 @@ func ParseTable(data []byte) (*Table, error) {
 				}
 			}
 		}
+		if raw, ok := item["quota"]; ok {
+			var q jsonQuota
+			if json.Unmarshal(raw, &q) == nil && strings.HasPrefix(q.Name, "quota_r") {
+				t.Quotas[q.Name] = q.bytes()
+			}
+		}
 		if raw, ok := item["set"]; ok {
 			var s jsonSet
 			if json.Unmarshal(raw, &s) != nil {
 				continue
 			}
+			if strings.HasPrefix(s.Name, "quota_r") {
+				for _, e := range s.Elem {
+					var w struct {
+						Elem struct {
+							Val   string     `json:"val"`
+							Quota *jsonQuota `json:"quota"`
+						} `json:"elem"`
+					}
+					if json.Unmarshal(e, &w) == nil && w.Elem.Quota != nil {
+						t.QuotaSets[s.Name] = append(t.QuotaSets[s.Name], render.Element{Addr: w.Elem.Val, Used: w.Elem.Quota.bytes()})
+					}
+				}
+				continue
+			}
 			name := strings.TrimSuffix(strings.TrimSuffix(s.Name, "_v4"), "_v6")
 			if name == s.Name || strings.HasPrefix(s.Name, "meter_") || strings.HasPrefix(s.Name, "conn_") {
 				continue
@@ -307,6 +388,37 @@ type Firewall struct {
 	mu    sync.Mutex
 	base  map[string]Counter
 	since time.Time
+	// restore is the quota usage saved before housecarld (or the machine)
+	// stopped, put back by the next apply.
+	restore *QuotaUsage
+}
+
+// RestoreQuotas has the next apply put this saved quota usage back where
+// the kernel's count is lower (after a reboot, the boot ruleset starts
+// every quota at zero).
+func (f *Firewall) RestoreQuotas(u *QuotaUsage) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.restore = u
+}
+
+// ResetQuota starts a rule's quota again: the named quota, or the
+// per-address quota sets (both families).
+func (f *Firewall) ResetQuota(ctx context.Context, ruleID int64, perAddress bool) error {
+	name := render.QuotaName(ruleID)
+	if !perAddress {
+		_, err := f.Runner.run(ctx, "", "reset", "quota", "inet", render.Table, name)
+		return err
+	}
+	for _, fam := range []string{"_v4", "_v6"} {
+		if _, err := f.Runner.run(ctx, "", "flush", "set", "inet", render.Table, name+fam); err != nil {
+			if e, ok := err.(*Error); ok && strings.Contains(e.Output, "No such file or directory") {
+				continue // the rule has no such family
+			}
+			return err
+		}
+	}
+	return nil
 }

 func (f *Firewall) options() render.Options {
@@ -337,9 +449,16 @@ func (f *Firewall) Apply(ctx context.Context, st *model.State) error {
 			old = t
 		}
 	}
+	usage := QuotaUsage{}
+	if old != nil {
+		usage = old.QuotaUsage
+	}
+	usage.merge(f.restore)
+	opt.Quotas, opt.QuotaSets = usage.Quotas, usage.QuotaSets
 	if err := f.Runner.Apply(ctx, render.Render(st, opt)); err != nil {
 		return err
 	}
+	f.restore = nil
 	if f.base == nil {
 		f.base, f.since = map[string]Counter{}, time.Now()
 	}
@@ -125,3 +125,86 @@ func TestFirewallInContainer(t *testing.T) {
 		t.Errorf("another table was touched: %s", out)
 	}
 }
+
+// TestQuotasInContainer: quotas keep what they used across a reload,
+// reset by hand, and come back after a reboot from what was saved.
+func TestQuotasInContainer(t *testing.T) {
+	image := os.Getenv("HOUSECARL_NFT_IMAGE")
+	if image == "" {
+		t.Skip("HOUSECARL_NFT_IMAGE not set")
+	}
+	name := "housecarl-nft-quota-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() })
+	fw := &Firewall{Runner: &Runner{Command: []string{"docker", "exec", "-i", name, "nft"}}}
+	ctx := context.Background()
+	st := model.NewState()
+	// A total quota on pings to 127.0.0.2, and one per destination on
+	// pings to 127.0.0.3.
+	st.Rules = []*model.Rule{
+		{ID: 1, Chain: model.ChainOutput, Position: 1, Action: model.ActionDrop, Match: model.Match{Destinations: []string{"127.0.0.2"}},
+			Quota: &model.Quota{Bytes: 10 << 20, Over: true}},
+		{ID: 2, Chain: model.ChainOutput, Position: 2, Action: model.ActionDrop, Match: model.Match{Destinations: []string{"127.0.0.3"}},
+			Quota: &model.Quota{Bytes: 10 << 20, Over: true, PerDestination: true}},
+	}
+	if err := fw.Apply(ctx, st); err != nil {
+		t.Fatalf("apply: %v", err)
+	}
+	ping := func(addr string) {
+		exec.Command("docker", "exec", name, "ping", "-c", "3", "-s", "1000", "-W", "1", addr).Run()
+	}
+	ping("127.0.0.2")
+	ping("127.0.0.3")
+	used := func() (int64, int64) {
+		tb, err := fw.Table(ctx)
+		if err != nil {
+			t.Fatal(err)
+		}
+		var dev int64
+		for _, e := range tb.QuotaSets["quota_r2_v4"] {
+			if e.Addr == "127.0.0.3" {
+				dev = e.Used
+			}
+		}
+		return tb.Quotas["quota_r1"], dev
+	}
+	total, dev := used()
+	if total < 3000 || dev < 3000 {
+		t.Fatalf("used: total %d, per destination %d", total, dev)
+	}
+	// A reload (a change) keeps what was used.
+	st.Rules[0].Comment = "changed"
+	if err := fw.Apply(ctx, st); err != nil {
+		t.Fatal(err)
+	}
+	if t2, d2 := used(); t2 < total || d2 < dev {
+		t.Errorf("after a reload: total %d (was %d), per destination %d (was %d)", t2, total, d2, dev)
+	}
+	// Reset by hand.
+	if err := fw.ResetQuota(ctx, 1, false); err != nil {
+		t.Fatal(err)
+	}
+	if err := fw.ResetQuota(ctx, 2, true); err != nil {
+		t.Fatal(err)
+	}
+	if t3, d3 := used(); t3 != 0 || d3 != 0 {
+		t.Errorf("after a reset: total %d, per destination %d", t3, d3)
+	}
+	// A reboot: the table is gone (the boot ruleset has no usage); the
+	// saved usage comes back.
+	ping("127.0.0.2")
+	ping("127.0.0.3")
+	tb, _ := fw.Table(ctx)
+	saved := tb.QuotaUsage
+	exec.Command("docker", "exec", name, "nft", "delete", "table", "inet", "housecarl").Run()
+	fw.RestoreQuotas(&saved)
+	if err := fw.Apply(ctx, st); err != nil {
+		t.Fatal(err)
+	}
+	if t4, d4 := used(); t4 < saved.Quotas["quota_r1"] || t4 == 0 || d4 == 0 {
+		t.Errorf("after a reboot: total %d, per destination %d (saved %+v)", t4, d4, saved)
+	}
+}