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>

cmd/hc/rules.go

@@ -3,6 +3,7 @@ package main
 import (
 	"fmt"
 	"io"
+	"regexp"
 	"strconv"
 	"strings"
 
@@ -96,8 +97,8 @@ type ruleFlags struct {
 	matchFlags
 	action, rejectWith, comment, logPrefix, raw string
 	states, statuses, days                      []string
-	hours, limit                                string
-	connLimit                                   int
+	hours, limit, quota                         string
+	connLimit, groupV4, groupV6                 int
 	log, disabled                               bool
 	before, after                               int64
 	first                                       bool
@@ -111,8 +112,11 @@ func (r *ruleFlags) register(f *pflag.FlagSet) {
 	f.StringSliceVar(&r.statuses, "status", nil, "connection status: dnat, snat")
 	f.StringSliceVar(&r.days, "days", nil, "days it applies: Monday,Tuesday,…")
 	f.StringVar(&r.hours, "hours", "", "hours it applies: 08:00-17:30 (22:00-06:00 passes midnight)")
-	f.StringVar(&r.limit, "limit", "", "a rate: 10/minute, with ,burst=N ,over (beyond the rate) ,per-source")
+	f.StringVar(&r.limit, "limit", "", "a rate: 10/minute, or bytes: 1mbytes/second, 500kbytes/minute; with ,burst=N ,over (beyond the rate) ,per-source or ,per-destination")
 	f.IntVar(&r.connLimit, "conn-limit", 0, "match a source with more than this many connections")
+	f.StringVar(&r.quota, "quota", "", "an allowance: 5000mbytes or 5gbytes, with ,over (match once used up) ,per-source or ,per-destination, and ,daily ,weekly or ,monthly=DAY to reset")
+	f.IntVar(&r.groupV4, "group-v4", 0, "per-source/destination limits and quotas count IPv4 addresses by this prefix (default 32: each address)")
+	f.IntVar(&r.groupV6, "group-v6", 0, "…and IPv6 addresses by this prefix (default 64: one device or network)")
 	f.BoolVar(&r.log, "log", false, "log matching packets ('hc log')")
 	f.StringVar(&r.logPrefix, "log-prefix", "", "the log line's prefix")
 	f.StringVar(&r.raw, "raw", "", "an nftables rule written by hand instead of the match flags")
@@ -120,35 +124,124 @@ func (r *ruleFlags) register(f *pflag.FlagSet) {
 	f.BoolVar(&r.disabled, "disabled", false, "keep the rule but don't use it")
 }
 
+var amountRe = regexp.MustCompile(`^(\d+)\s*([a-zA-Z]*)$`)
+
+// byteUnit reads a unit: "" (packets, for rates), bytes, kbytes, mbytes,
+// gbytes, or b, kb, mb, gb in any case.
+func byteUnit(u string) (string, bool) {
+	switch strings.ToLower(u) {
+	case "", "packets", "packet", "p":
+		return "", true
+	case "bytes", "byte", "b":
+		return "bytes", true
+	case "kbytes", "kb", "k":
+		return "kbytes", true
+	case "mbytes", "mb", "m":
+		return "mbytes", true
+	case "gbytes", "gb", "g":
+		return "gbytes", true
+	}
+	return "", false
+}
+
 func parseLimit(s string) (*model.Limit, error) {
 	if s == "" {
 		return nil, nil
 	}
 	parts := strings.Split(s, ",")
 	rate, per, ok := strings.Cut(strings.TrimSpace(parts[0]), "/")
-	n, err := strconv.Atoi(rate)
-	if !ok || err != nil {
-		return nil, fmt.Errorf("--limit %q: write it as 10/minute, with ,burst=N ,over ,per-source", s)
+	m := amountRe.FindStringSubmatch(strings.TrimSpace(rate))
+	unit, unitOK := "", false
+	if m != nil {
+		unit, unitOK = byteUnit(m[2])
 	}
-	l := &model.Limit{Rate: n, Per: strings.TrimSuffix(per, "s")}
+	if !ok || m == nil || !unitOK || unit == "gbytes" {
+		return nil, fmt.Errorf("--limit %q: write it as 10/minute, or as bytes 1mbytes/second (bytes, kbytes, mbytes), with ,burst=N ,over ,per-source", s)
+	}
+	n, _ := strconv.Atoi(m[1])
+	l := &model.Limit{Rate: n, Unit: unit, Per: strings.TrimSuffix(per, "s")}
 	for _, p := range parts[1:] {
 		k, v, _ := strings.Cut(strings.TrimSpace(p), "=")
 		switch k {
 		case "burst":
-			if l.Burst, err = strconv.Atoi(v); err != nil {
-				return nil, fmt.Errorf("--limit: burst=%q isn't a number", v)
+			b := amountRe.FindStringSubmatch(v)
+			bu, buOK := "", false
+			if b != nil {
+				bu, buOK = byteUnit(b[2])
 			}
+			if b == nil || !buOK || (b[2] != "" && bu != unit) {
+				return nil, fmt.Errorf("--limit: burst=%q: a number, in the rate's unit", v)
+			}
+			l.Burst, _ = strconv.Atoi(b[1])
 		case "over":
 			l.Over = true
 		case "per-source":
 			l.PerSource = true
+		case "per-destination":
+			l.PerDestination = true
 		default:
-			return nil, fmt.Errorf("--limit: unknown %q (burst=N, over, per-source)", k)
+			return nil, fmt.Errorf("--limit: unknown %q (burst=N, over, per-source, per-destination)", k)
 		}
 	}
 	return l, nil
 }
 
+// parseQuota reads --quota: 5000mbytes,over,per-source,monthly=15.
+func parseQuota(s string) (*model.Quota, error) {
+	if s == "" {
+		return nil, nil
+	}
+	parts := strings.Split(s, ",")
+	m := amountRe.FindStringSubmatch(strings.TrimSpace(parts[0]))
+	unit, ok := "", false
+	if m != nil {
+		unit, ok = byteUnit(m[2])
+	}
+	if m == nil || !ok || unit == "" {
+		return nil, fmt.Errorf("--quota %q: write it as 5000mbytes or 5gbytes, with ,over ,per-source ,daily ,weekly or ,monthly=DAY", s)
+	}
+	n, _ := strconv.ParseInt(m[1], 10, 64)
+	q := &model.Quota{Bytes: n * model.ByteUnits[unit]}
+	for _, p := range parts[1:] {
+		k, v, _ := strings.Cut(strings.TrimSpace(p), "=")
+		switch k {
+		case "over":
+			q.Over = true
+		case "per-source":
+			q.PerSource = true
+		case "per-destination":
+			q.PerDestination = true
+		case "daily", "weekly":
+			q.Reset = k
+		case "monthly":
+			q.Reset = k
+			if v != "" {
+				d, err := strconv.Atoi(v)
+				if err != nil {
+					return nil, fmt.Errorf("--quota: monthly=%q: the day of the month, 1 to 31", v)
+				}
+				q.Day = d
+			}
+		default:
+			return nil, fmt.Errorf("--quota: unknown %q (over, per-source, per-destination, daily, weekly, monthly=DAY)", k)
+		}
+	}
+	return q, nil
+}
+
+// humanBytes writes bytes for people: "1.8 GB".
+func humanBytes(n int64) string {
+	switch {
+	case n >= 1<<30:
+		return strconv.FormatFloat(float64(n)/(1<<30), 'f', 1, 64) + " GB"
+	case n >= 1<<20:
+		return strconv.FormatFloat(float64(n)/(1<<20), 'f', 1, 64) + " MB"
+	case n >= 1<<10:
+		return strconv.FormatFloat(float64(n)/(1<<10), 'f', 1, 64) + " KB"
+	}
+	return strconv.FormatInt(n, 10) + " bytes"
+}
+
 func (r *ruleFlags) rule(chain string) (model.Rule, error) {
 	rule := model.Rule{Chain: chain, Match: r.match(), Action: r.action, RejectWith: r.rejectWith, CtState: r.states, CtStatus: r.statuses,
 		Days: r.days, ConnLimit: r.connLimit, Log: r.log, LogPrefix: r.logPrefix, Raw: r.raw, Comment: r.comment, Disabled: r.disabled}
@@ -160,7 +253,12 @@ func (r *ruleFlags) rule(chain string) (model.Rule, error) {
 		rule.HourFrom, rule.HourTo = from, to
 	}
 	l, err := parseLimit(r.limit)
+	if err != nil {
+		return rule, err
+	}
 	rule.Limit = l
+	rule.Quota, err = parseQuota(r.quota)
+	rule.GroupV4, rule.GroupV6 = r.groupV4, r.groupV6
 	return rule, err
 }
 
@@ -221,7 +319,7 @@ output (from it) or early (before connection tracking: cheap drops).
 
   hc rule add input --from trusted --service ssh
   hc rule add input --in wg --service dns
-  hc rule add forward --in lan --out wan --from 2a02:8013:7f3d:10::/64
+  hc rule add forward --in lan --out wan --from 2001:db8:1::/64
   hc rule add input --in wan --service ssh --limit 3/minute,burst=5,over,per-source -a drop --log
   hc rule add forward --in wan -a drop --comment "nothing else gets in"
   hc rule add forward --raw 'iifname != "wan" ct state invalid ip daddr @trusted_v4 accept'`,
@@ -277,7 +375,7 @@ output (from it) or early (before connection tracking: cheap drops).
 				"action": {"action", r.Action}, "reject-with": {"reject_with", r.RejectWith}, "state": {"ct_state", r.CtState},
 				"status": {"ct_status", r.CtStatus}, "days": {"days", r.Days}, "conn-limit": {"conn_limit", r.ConnLimit},
 				"log": {"log", r.Log}, "log-prefix": {"log_prefix", r.LogPrefix}, "raw": {"raw", r.Raw}, "comment": {"comment", r.Comment},
-				"disabled": {"disabled", r.Disabled},
+				"disabled": {"disabled", r.Disabled}, "group-v4": {"group_v4", r.GroupV4}, "group-v6": {"group_v6", r.GroupV6},
 			} {
 				if fl.Changed(flag) {
 					p[field[0].(string)] = field[1]
@@ -289,6 +387,9 @@ output (from it) or early (before connection tracking: cheap drops).
 			if fl.Changed("limit") {
 				p["limit"] = r.Limit
 			}
+			if fl.Changed("quota") {
+				p["quota"] = r.Quota
+			}
 			return change("PATCH", objPath("rules", args[0]), p)
 		},
 	}
@@ -316,6 +417,22 @@ output (from it) or early (before connection tracking: cheap drops).
 	move.Flags().BoolVar(&last, "last", false, "last in its chain")
 	move.Flags().StringVar(&chain, "chain", "", "to the end of another chain")
 	cmd.AddCommand(move)
+	cmd.AddCommand(&cobra.Command{
+		Use: "reset-quota ID", Short: "Start a rule's quota again now (every address's, for a per-address quota)", Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newClient()
+			if err != nil {
+				return err
+			}
+			if err := c.Do(ctx(), "POST", objPath("rules", args[0])+"/reset-quota", nil, nil, nil); err != nil {
+				return err
+			}
+			if !flagQuiet {
+				fmt.Printf("reset the quota of rule %s\n", args[0])
+			}
+			return nil
+		},
+	})
 	for _, on := range []bool{true, false} {
 		verb, short := "disable", "Keep a rule but don't use it"
 		if on {
@@ -345,13 +462,39 @@ func ruleExtras(r model.Rule) string {
 		x = append(x, r.HourFrom+"-"+r.HourTo)
 	}
 	if l := r.Limit; l != nil {
-		s := fmt.Sprintf("limit %d/%s", l.Rate, l.Per)
+		unit := ""
+		if l.Unit != "" && l.Unit != "packets" {
+			unit = " " + l.Unit
+		}
+		s := fmt.Sprintf("limit %d%s/%s", l.Rate, unit, l.Per)
 		if l.Over {
 			s = "over " + s
 		}
 		if l.PerSource {
 			s += " per source"
 		}
+		if l.PerDestination {
+			s += " per destination"
+		}
+		x = append(x, s)
+	}
+	if q := r.Quota; q != nil {
+		s := "quota " + humanBytes(q.Bytes)
+		if q.Over {
+			s = "over " + s
+		}
+		if q.PerSource {
+			s += " per source"
+		}
+		if q.PerDestination {
+			s += " per destination"
+		}
+		switch {
+		case q.Reset == "monthly" && q.Day > 1:
+			s += fmt.Sprintf(" monthly (%d)", q.Day)
+		case q.Reset != "":
+			s += " " + q.Reset
+		}
 		x = append(x, s)
 	}
 	if r.ConnLimit > 0 {
@@ -412,9 +555,9 @@ through, and with --hairpin makes the public address work from inside too.
 --to6 also opens the port to an IPv6 host (no translation there: its own
 port).
 
-  hc forward add 8096 --to 10.0.10.57:443 --to6 2a02:8013:7f3d:10::57 --public 217.155.8.194 --hairpin --name jellyfin
-  hc forward add 7777-7780 --proto tcp,udp --to 10.0.10.76 --public 217.155.8.194 --hairpin --name terraria
-  hc forward add 25 --to 10.0.10.25 --from trusted`,
+  hc forward add 8443 --to 192.168.1.10:443 --to6 2001:db8:1::10 --public 203.0.113.10 --hairpin --name web
+  hc forward add 27015-27030 --proto tcp,udp --to 192.168.1.20 --public 203.0.113.10 --hairpin --name game
+  hc forward add 25 --to 192.168.1.25 --from trusted`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			pf.Ports = args[0]
 			if to != "" {
@@ -528,7 +671,7 @@ traffic leaving the firewall. IPv4 only, unless --family ipv6 (NAT66).
 
   hc snat add --out wan --from trusted
   hc snat add --out wg --not-out --from wg_net
-  hc snat add --out wan --from fdab:abab:abab::/48 --family ipv6 --snat-to 2a02:8013:7f3d::1`,
+  hc snat add --out wan --from fd00:1::/48 --family ipv6 --snat-to 2001:db8::1`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return change("POST", "/snats", model.SourceNAT{Match: mf.match(), To: to, Comment: comment})
 		},
@@ -606,7 +749,7 @@ func redirectCmd() *cobra.Command {
 		Long: `Sends matching traffic to a port on the firewall itself, so every client
 uses its DNS server, say:
 
-  hc redirect add --in lan --service dns --not-to 10.0.10.5 --comment "force DNS"`,
+  hc redirect add --in lan --service dns --not-to 192.168.1.5 --comment "force DNS"`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return change("POST", "/redirects", model.Redirect{Match: mf.match(), ToPort: toPort, Comment: comment})
 		},