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/changesets.go

@@ -0,0 +1,377 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strconv"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"housecarl/internal/api"
+	"housecarl/internal/client"
+	"housecarl/internal/model"
+)
+
+// Changesets: configuration changes staged to be reviewed and applied
+// together. -C/--changeset stages into a changeset as given (housecarld
+// still refuses one that isn't open, or another user's unless you are an
+// administrator). One from HOUSECARL_CHANGESET is checked first: an
+// exported ID outlives its changeset (it gets applied), and IDs keep
+// growing, so a stale or mistyped one could name someone else's later. It
+// is used only when it is open and yours, and hc says on stderr which
+// changeset that is.
+
+var flagChangeset int64
+
+// envChangeset returns the changeset in HOUSECARL_CHANGESET (0 if unset).
+func envChangeset() (int64, error) {
+	v := os.Getenv("HOUSECARL_CHANGESET")
+	if v == "" {
+		return 0, nil
+	}
+	n, err := strconv.ParseInt(v, 10, 64)
+	if err != nil || n <= 0 {
+		return 0, fmt.Errorf("invalid HOUSECARL_CHANGESET %q", v)
+	}
+	return n, nil
+}
+
+const startHint = "export HOUSECARL_CHANGESET=$(hc changeset create -q)"
+
+// checkEnvChangeset checks the changeset from HOUSECARL_CHANGESET before
+// it is used. With mustOwn, it must also be open and the caller's own
+// (for staging into it, applying or discarding it).
+func checkEnvChangeset(c *client.Client, id int64, mustOwn bool) (*model.Changeset, error) {
+	var cs model.Changeset
+	if err := c.Do(ctx(), "GET", fmt.Sprintf("/changesets/%d", id), nil, nil, &cs); err != nil {
+		var ce *client.Error
+		if errors.As(err, &ce) && ce.Status == 404 {
+			return nil, fmt.Errorf("HOUSECARL_CHANGESET is %d, but there is no changeset %d: start one with '%s', or 'unset HOUSECARL_CHANGESET' to make changes at once", id, id, startHint)
+		}
+		return nil, err
+	}
+	if mustOwn {
+		if cs.Status != model.ChangesetOpen {
+			return nil, fmt.Errorf("HOUSECARL_CHANGESET is %d, but changeset %d is %s: 'unset HOUSECARL_CHANGESET' to make changes at once, or start a new one with '%s'", id, id, cs.Status, startHint)
+		}
+		var me api.Whoami
+		if err := c.Do(ctx(), "GET", "/auth/whoami", nil, nil, &me); err != nil {
+			return nil, err
+		}
+		mine := me.User != nil && cs.UserID == me.User.ID && (me.User.ID != 0 || cs.Username == me.User.Username)
+		if !mine {
+			return nil, fmt.Errorf("HOUSECARL_CHANGESET is %d, but changeset %d is %s's (made via %s), not yours, so it isn't used from HOUSECARL_CHANGESET; give it as -C %d to use it anyway, or 'unset HOUSECARL_CHANGESET'", id, id, cs.Username, cs.Via, id)
+		}
+	}
+	if !flagQuiet {
+		desc := cs.Description
+		if desc == "" {
+			desc = "no description"
+		}
+		fmt.Fprintf(os.Stderr, "changeset %d (%s, %s) from HOUSECARL_CHANGESET\n", id, desc, plural(len(cs.Ops), "operation"))
+	}
+	return &cs, nil
+}
+
+// setupChangeset makes the client stage configuration changes: in
+// --changeset's changeset, else HOUSECARL_CHANGESET's (checked before
+// the first change).
+func setupChangeset(c *client.Client) error {
+	if flagChangeset > 0 {
+		c.Changeset = flagChangeset
+		return nil
+	}
+	n, err := envChangeset()
+	if err != nil || n == 0 {
+		return err
+	}
+	c.Changeset = n
+	c.BeforeStage = func() error {
+		_, err := checkEnvChangeset(c, n, true)
+		return err
+	}
+	return nil
+}
+
+// changesetArg returns the changeset a changeset subcommand works on: the
+// ID argument, else --changeset, else HOUSECARL_CHANGESET (checked).
+// fromEnv says it came from HOUSECARL_CHANGESET.
+func changesetArg(c *client.Client, args []string, mustOwn bool) (id string, fromEnv bool, err error) {
+	if len(args) > 0 {
+		return args[0], false, nil
+	}
+	if flagChangeset > 0 {
+		return strconv.FormatInt(flagChangeset, 10), false, nil
+	}
+	n, err := envChangeset()
+	if err != nil {
+		return "", false, err
+	}
+	if n == 0 {
+		return "", false, errors.New("which changeset? Give its ID, or set HOUSECARL_CHANGESET (" + startHint + ")")
+	}
+	if _, err := checkEnvChangeset(c, n, mustOwn); err != nil {
+		return "", false, err
+	}
+	return strconv.FormatInt(n, 10), true, nil
+}
+
+// envChangesetDone reminds that HOUSECARL_CHANGESET still names a
+// changeset that was just applied or discarded.
+func envChangesetDone(id, what string) {
+	if !flagQuiet {
+		fmt.Fprintf(os.Stderr, "HOUSECARL_CHANGESET still names changeset %s, which is now %s: run 'unset HOUSECARL_CHANGESET' (or export a new one) before making more changes\n", id, what)
+	}
+}
+
+func plural(n int, word string) string {
+	if n == 1 {
+		return "1 " + word
+	}
+	return strconv.Itoa(n) + " " + word + "s"
+}
+
+// printDiff prints a unified diff, colored on a terminal.
+func printDiff(w io.Writer, diff string) {
+	color := isTerminal(os.Stdout)
+	for _, line := range strings.Split(strings.TrimSuffix(diff, "\n"), "\n") {
+		switch {
+		case !color:
+		case strings.HasPrefix(line, "+++"), strings.HasPrefix(line, "---"):
+			line = "\x1b[1m" + line + "\x1b[0m"
+		case strings.HasPrefix(line, "+"):
+			line = "\x1b[32m" + line + "\x1b[0m"
+		case strings.HasPrefix(line, "-"):
+			line = "\x1b[31m" + line + "\x1b[0m"
+		case strings.HasPrefix(line, "@@"):
+			line = "\x1b[36m" + line + "\x1b[0m"
+		}
+		fmt.Fprintln(w, line)
+	}
+}
+
+func isTerminal(f *os.File) bool {
+	fi, err := f.Stat()
+	return err == nil && fi.Mode()&os.ModeCharDevice != 0
+}
+
+func changesetCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "changeset",
+		Aliases: []string{"changesets", "cs"},
+		Short:   "Stage changes to review and apply together",
+		Long: `A changeset collects configuration changes to apply together, as one
+change in the history. Each change is checked as it is staged; 'hc
+changeset diff' shows what applying them would do: the problems, nftables'
+check and the ruleset's diff. Over the network an applied changeset is on
+probation like any change.
+
+The web UI stages its edits in a changeset by default; hc and the API
+make changes at once unless one is named with -C ID or HOUSECARL_CHANGESET.
+Changesets staged in the web UI show up here too, and the other way round.`,
+		Example: `  export HOUSECARL_CHANGESET=$(hc changeset create "guest network" -q)
+  hc zone add guest -i eth1.30
+  hc rule add forward --in guest --out wan
+  hc changeset diff                 # HOUSECARL_CHANGESET's
+  hc changeset apply
+  unset HOUSECARL_CHANGESET`,
+	}
+	cmd.AddCommand(&cobra.Command{
+		Use: "create [DESCRIPTION]", Short: "Start a changeset (-q prints only its ID)", Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newClient()
+			if err != nil {
+				return err
+			}
+			in := api.ChangesetInput{}
+			if len(args) > 0 {
+				in.Description = args[0]
+			}
+			var cs model.Changeset
+			if err := c.Do(ctx(), "POST", "/changesets", nil, in, &cs); err != nil {
+				return err
+			}
+			if flagQuiet || flagOutput == "id" {
+				fmt.Println(cs.ID)
+				return nil
+			}
+			fmt.Printf("created changeset %d\nstage changes with -C %d (or export HOUSECARL_CHANGESET=%d), then 'hc changeset apply'\n", cs.ID, cs.ID, cs.ID)
+			return nil
+		},
+	})
+	var status string
+	var mine bool
+	list := &cobra.Command{
+		Use: "list", Short: "List changesets (open ones by default)", Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newClient()
+			if err != nil {
+				return err
+			}
+			var css []*model.Changeset
+			query := q("status", status)
+			if mine {
+				query.Set("mine", "1")
+			}
+			if err := c.Do(ctx(), "GET", "/changesets", query, nil, &css); err != nil {
+				return err
+			}
+			return output(css, func(w io.Writer) {
+				fmt.Fprintln(w, "ID\tSTATUS\tBY\tVIA\tOPERATIONS\tUPDATED\tDESCRIPTION")
+				for _, cs := range css {
+					fmt.Fprintf(w, "%d\t%s\t%s\t%s\t%d\t%s\t%s\n", cs.ID, cs.Status, cs.Username, cs.Via, len(cs.Ops), cs.UpdatedAt.Local().Format("2006-01-02 15:04"), cs.Description)
+				}
+			})
+		},
+	}
+	list.Flags().StringVar(&status, "status", "open", "open, applied, discarded, or \"\" for all")
+	list.Flags().BoolVar(&mine, "mine", false, "only your own")
+	cmd.AddCommand(list)
+	cmd.AddCommand(&cobra.Command{
+		Use: "show [ID]", Short: "Show a changeset's operations (default: -C or HOUSECARL_CHANGESET)", Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newClient()
+			if err != nil {
+				return err
+			}
+			id, _, err := changesetArg(c, args, false)
+			if err != nil {
+				return err
+			}
+			var cs model.Changeset
+			if err := c.Do(ctx(), "GET", "/changesets/"+id, nil, nil, &cs); err != nil {
+				return err
+			}
+			return output(&cs, func(w io.Writer) {
+				fmt.Fprintf(w, "Changeset:\t%d (%s)\n", cs.ID, cs.Status)
+				fmt.Fprintf(w, "By:\t%s via %s, %s\n", cs.Username, cs.Via, cs.CreatedAt.Local().Format("2006-01-02 15:04"))
+				if cs.Description != "" {
+					fmt.Fprintf(w, "Description:\t%s\n", cs.Description)
+				}
+				if cs.HistoryID != 0 {
+					fmt.Fprintf(w, "History:\t%d\n", cs.HistoryID)
+				}
+				fmt.Fprintln(w, "\nOP\tCHANGE")
+				for _, o := range cs.Ops {
+					fmt.Fprintf(w, "%d\t%s\n", o.Seq, o.Summary)
+				}
+			})
+		},
+	})
+	cmd.AddCommand(&cobra.Command{
+		Use: "diff [ID]", Short: "Check an open changeset and show what applying it would change (default: -C or HOUSECARL_CHANGESET)", Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newClient()
+			if err != nil {
+				return err
+			}
+			id, _, err := changesetArg(c, args, false)
+			if err != nil {
+				return err
+			}
+			var pv api.ChangesetPreview
+			if err := c.Do(ctx(), "GET", "/changesets/"+id+"/preview", nil, nil, &pv); err != nil {
+				return err
+			}
+			if flagOutput == "json" || flagOutput == "yaml" {
+				return output(&pv, nil)
+			}
+			for _, ch := range pv.Changes {
+				if ch.Kind == model.KindSettings {
+					fmt.Printf("would %s settings\n", ch.Action())
+				} else {
+					fmt.Printf("would %s %s %s\n", ch.Action(), ch.Kind, ch.Label)
+				}
+			}
+			printProblems(os.Stderr, pv.Warnings)
+			if pv.Error != nil {
+				printProblems(os.Stderr, pv.Error.Problems)
+				return fmt.Errorf("changeset %s can't be applied: %s", id, pv.Error.Message)
+			}
+			if !pv.Valid {
+				fmt.Println("nothing to change")
+				return nil
+			}
+			fmt.Println()
+			printDiff(os.Stdout, pv.Diff)
+			fmt.Printf("\nvalid: nftables accepts the new ruleset; apply with 'hc changeset apply %s'\n", id)
+			return nil
+		},
+	})
+	var desc string
+	apply := &cobra.Command{
+		Use: "apply [ID]", Short: "Apply an open changeset (default: -C or HOUSECARL_CHANGESET)", Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newClient()
+			if err != nil {
+				return err
+			}
+			id, fromEnv, err := changesetArg(c, args, true)
+			if err != nil {
+				return err
+			}
+			var resp api.MutationResponse
+			if err := c.Do(ctx(), "POST", "/changesets/"+id+"/apply", nil, api.ChangesetInput{Description: desc}, &resp); err != nil {
+				return err
+			}
+			if err := report(&resp); err != nil {
+				return err
+			}
+			if fromEnv {
+				envChangesetDone(id, "applied")
+			}
+			return nil
+		},
+	}
+	apply.Flags().StringVar(&desc, "description", "", "the history entry's description (default: the changeset's)")
+	cmd.AddCommand(apply)
+	cmd.AddCommand(&cobra.Command{
+		Use: "discard [ID]", Short: "Throw away an open changeset (default: -C or HOUSECARL_CHANGESET)", Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newClient()
+			if err != nil {
+				return err
+			}
+			id, fromEnv, err := changesetArg(c, args, true)
+			if err != nil {
+				return err
+			}
+			if err := c.Do(ctx(), "POST", "/changesets/"+id+"/discard", nil, nil, nil); err != nil {
+				return err
+			}
+			if !flagQuiet {
+				fmt.Printf("discarded changeset %s\n", id)
+			}
+			if fromEnv {
+				envChangesetDone(id, "discarded")
+			}
+			return nil
+		},
+	})
+	cmd.AddCommand(&cobra.Command{
+		Use: "remove [ID] OP", Short: "Remove one operation from an open changeset (default: -C or HOUSECARL_CHANGESET)", Args: cobra.RangeArgs(1, 2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newClient()
+			if err != nil {
+				return err
+			}
+			op := args[len(args)-1]
+			id, _, err := changesetArg(c, args[:len(args)-1], true)
+			if err != nil {
+				return err
+			}
+			var cs model.Changeset
+			if err := c.Do(ctx(), "DELETE", "/changesets/"+id+"/ops/"+op, nil, nil, &cs); err != nil {
+				return err
+			}
+			if !flagQuiet {
+				fmt.Printf("removed operation %s; changeset %s has %s\n", op, id, plural(len(cs.Ops), "operation"))
+			}
+			return nil
+		},
+	})
+	return cmd
+}

cmd/hc/firewall.go

@@ -136,9 +136,9 @@ func settingsCmd() *cobra.Command {
 turned off: loopback, established, drop_invalid, icmpv6, ping_internal,
 dhcpv6_client, antispoof, mss_clamp.
 
-  hc settings set --builtin mss_clamp=on --own-prefix 2a02:8013:7f3d::/48
+  hc settings set --builtin mss_clamp=on --own-prefix 2001:db8::/48
   hc settings set --forward-policy drop --log-drops on
-  hc settings set --flowtable wan --flowtable enp2s0`,
+  hc settings set --flowtable wan --flowtable eth1`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			fl := cmd.Flags()
 			p := patch{}
@@ -252,6 +252,41 @@ func countersCmd() *cobra.Command {
 	}
 }
 
+func quotasCmd() *cobra.Command {
+	return &cobra.Command{
+		Use: "quotas", Aliases: []string{"quota"}, Short: "What the rules' quotas used, and when they reset", Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			qs, err := get[[]api.QuotaInfo]("/quotas", nil)
+			if err != nil {
+				return err
+			}
+			return output(qs, func(w io.Writer) {
+				fmt.Fprintln(w, "RULE\tUSED\tOF\tRESETS\tNEXT RESET")
+				for _, q := range qs {
+					resets := q.Quota.Reset
+					if resets == "" {
+						resets = "by hand"
+					} else if resets == "monthly" && q.Quota.Day > 1 {
+						resets = fmt.Sprintf("monthly (%d)", q.Quota.Day)
+					}
+					next := "-"
+					if q.NextReset != nil {
+						next = q.NextReset.Local().Format("2006-01-02 15:04")
+					}
+					of := humanBytes(q.Quota.Bytes)
+					if q.Quota.PerSource || q.Quota.PerDestination {
+						of += " each"
+					}
+					fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\n", q.Rule, humanBytes(q.Used), of, resets, next)
+					for _, a := range q.Addresses {
+						fmt.Fprintf(w, "  %s\t%s\t\t\t\n", a.Address, humanBytes(a.Used))
+					}
+				}
+			})
+		},
+	}
+}
+
 func logCmd() *cobra.Command {
 	var follow bool
 	var limit int
@@ -383,7 +418,7 @@ forwards and NAT. The input is nft's JSON; on the firewall:
 Without a FILE, hc runs 'nft -j list ruleset' and 'nft -a list ruleset'
 itself (root on the firewall); from elsewhere, give the JSON as FILE and
 the text with --text. --defines reads the ruleset file's define lines, to
-name the sets as you did (trusted_ips, wg0_net, …). -n shows the result without
+name the sets as you did (admins, lan_net, …). -n shows the result without
 saving; what can't be expressed becomes raw rules, listed with notes.
 Once it looks right, import without -n, check it with 'hc ruleset', and
 'hc takeover inet main' deletes the old table.`,

cmd/hc/main.go

@@ -132,6 +132,9 @@ func newClient() (*client.Client, error) {
 		return nil, err
 	}
 	c.DryRun = flagDryRun
+	if err := setupChangeset(c); err != nil {
+		return nil, err
+	}
 	return c, nil
 }
 
@@ -143,7 +146,10 @@ func rootCmd() *cobra.Command {
 
 Every change is checked as a whole, then by nftables, before it is put in
 force, and is recorded in the history, where 'hc history undo ID' takes it
-back. --dry-run shows what a change would do.
+back. --dry-run shows what a change would do, with the ruleset's diff.
+Changes are made at once; to review several and apply them together,
+stage them in a changeset ('hc changeset --help', -C ID or
+HOUSECARL_CHANGESET).
 
 A change made over the network is on probation: confirm it with 'hc
 confirm' (within 2 minutes by default) or it is rolled back by itself, so a
@@ -169,6 +175,7 @@ Exit codes: 0 ok, 1 error, 3 not authenticated or not allowed, 4 not found,
 	pf.BoolVar(&flagInsecure, "insecure", false, "don't verify the server's TLS certificate")
 	pf.StringVar(&flagCACert, "ca-cert", "", "PEM file with a CA to trust for the server's certificate")
 	pf.BoolVarP(&flagQuiet, "quiet", "q", false, "print only errors (and IDs of new objects)")
+	pf.Int64VarP(&flagChangeset, "changeset", "C", 0, "stage configuration changes in this changeset instead of applying them (env HOUSECARL_CHANGESET)")
 	root.AddGroup(&cobra.Group{ID: "fw", Title: "Firewall:"}, &cobra.Group{ID: "changes", Title: "Changes:"}, &cobra.Group{ID: "admin", Title: "Administration:"})
 	add := func(group string, cmds ...*cobra.Command) {
 		for _, c := range cmds {
@@ -177,8 +184,8 @@ Exit codes: 0 ok, 1 error, 3 not authenticated or not allowed, 4 not found,
 		}
 	}
 	add("fw", statusCmd(), zoneCmd(), setCmd(), serviceCmd(), ruleCmd(), forwardCmd(), snatCmd(), redirectCmd(), settingsCmd(),
-		rulesetCmd(), countersCmd(), logCmd(), interfaceCmd())
-	add("changes", confirmCmd(), rollbackCmd(), historyCmd(), importCmd(), takeoverCmd())
+		rulesetCmd(), countersCmd(), quotasCmd(), logCmd(), interfaceCmd())
+	add("changes", changesetCmd(), confirmCmd(), rollbackCmd(), historyCmd(), importCmd(), takeoverCmd())
 	add("admin", whoamiCmd(), userCmd(), tokenCmd(), passwordCmd(), certCmd(), auditCmd(), configCmd())
 	return root
 }
@@ -237,8 +244,6 @@ func outputIDs(v any) error {
 		if m, ok := it.(map[string]any); ok {
 			if id, ok := m["id"]; ok {
 				fmt.Println(id)
-			} else if ip, ok := m["ip"]; ok {
-				fmt.Println(ip)
 			}
 		}
 	}
@@ -310,6 +315,9 @@ func report(resp *api.MutationResponse) error {
 		if resp.DryRun {
 			return "would " + c.Action()
 		}
+		if resp.Staged {
+			return "staged: " + c.Action()
+		}
 		return c.Action() + "d"
 	}
 	if !flagQuiet || resp.DryRun {
@@ -322,7 +330,18 @@ func report(resp *api.MutationResponse) error {
 		}
 	}
 	switch {
+	case resp.Staged && resp.Changeset != nil:
+		if !flagQuiet {
+			cs := resp.Changeset
+			fmt.Fprintf(w, "staged in changeset %d as operation %d (%s now); review with 'hc changeset diff %d', apply with 'hc changeset apply %d'\n",
+				cs.ID, cs.Ops[len(cs.Ops)-1].Seq, plural(len(cs.Ops), "operation"), cs.ID, cs.ID)
+		}
 	case resp.DryRun:
+		if resp.Diff != "" && !flagQuiet {
+			fmt.Fprintln(w)
+			printDiff(w, resp.Diff)
+			fmt.Fprintln(w)
+		}
 		fmt.Fprintln(w, "dry run: nothing was changed")
 	case resp.Applied && resp.ConfirmBy != nil:
 		fmt.Fprintf(w, "applied on probation (history %d): confirm with 'hc confirm' within %s, or it is rolled back\n",
@@ -332,7 +351,7 @@ func report(resp *api.MutationResponse) error {
 	case !resp.Applied && len(resp.Changes) == 0 && !flagQuiet:
 		fmt.Fprintln(w, "nothing to change")
 	}
-	if flagQuiet && len(resp.Object) > 0 && resp.Applied {
+	if flagQuiet && len(resp.Object) > 0 && (resp.Applied || resp.Staged) {
 		outputIDs(resp.Object)
 	}
 	printProblems(os.Stderr, resp.Warnings)

cmd/hc/objects.go

@@ -144,7 +144,7 @@ many: --interface 'incusbr*'. --external marks a zone facing the internet:
 antispoofing, MSS clamping and port forwards apply there.
 
   hc zone add wan --interface wan --external
-  hc zone add lan --interface enp2s0`,
+  hc zone add lan --interface eth1`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return change("POST", "/zones", model.Zone{Name: args[0], Interfaces: ifaces, External: external, Comment: comment})
 		},
@@ -267,7 +267,7 @@ func setCmd() *cobra.Command {
 		Use: "add NAME [ENTRY...]", Short: "Add a set", Args: cobra.MinimumNArgs(1),
 		Long: `Adds a set of addresses, prefixes and ranges, IPv4 and IPv6 mixed:
 
-  hc set add trusted 10.0.10.0/24 10.20.30.0/24 2a02:8013:7f3d:10::/64
+  hc set add trusted 192.168.1.0/24 192.168.2.0/24 2001:db8:1::/64
   hc set add guests --dynamic --timeout 24h
 
 A dynamic set takes entries at run time, each with its own timeout ('hc
@@ -425,7 +425,7 @@ func serviceCmd() *cobra.Command {
 		Use: "add NAME ENTRY...", Short: "Add a service", Args: cobra.MinimumNArgs(2),
 		Long: `Adds a service: ports of a protocol, and ICMP types.
 
-  hc service add jellyfin tcp/8096 tcp/8920
+  hc service add web tcp/8080 tcp/8443
   hc service add games udp/27015-27030 tcp/27015
   hc service add pmtu icmp/destination-unreachable icmpv6/packet-too-big`,
 		RunE: func(cmd *cobra.Command, args []string) error {

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})
 		},