housecarl/CHANGELOG.md

Changelog

All notable changes to Housecarl are documented here. The format follows Keep a Changelog, and versions follow Semantic Versioning.

[Unreleased]

The first version of Housecarl, a firewall manager for nftables, built the way Jarl and Steward are.

Added

• Zones, address sets and services: interfaces grouped by what they connect to (wildcards like incusbr*; external zones face the internet); sets of IPv4 and IPv6 addresses, prefixes and ranges, mixed; ports and ICMP types by name, with twenty built in (docs/rules.md).
• Rules in four chains (input, forward, output, and early, before connection tracking), in order, matching by zone, address, service, family, connection state and status, days and hours, a rate (also per source address), and a connection count; accept, drop, reject (ICMP or TCP reset) or log. Raw nftables rules for the rest.
• IPv4 and IPv6 together: one rule becomes the nftables rules each family needs.
• NAT: port forwards as one object (DNAT, the forward accept, hairpin NAT, and optionally an IPv6 pinhole to a host's own port); source NAT (masquerade or an address; NAT66 on request); redirects to the firewall (docs/nat.md).
• Built-ins, each switchable: loopback, established connections, invalid packets, ICMPv6 (RFC 4890), ping from internal zones, DHCPv6 client replies, antispoofing with your own prefixes, MSS clamping, and a flowtable fast path.
• Changesets, as in Jarl: changes staged to be reviewed and applied together, as one history entry. Each is checked as it is staged; the review shows the problems, nftables' check and the diff of the ruleset. The web UI collects edits as pending changes by default (pending rows, a bar with Review and Apply now, a Changes page), with a switch for live edits, and Undo in History is staged like any edit; hc stages with -C ID or HOUSECARL_CHANGESET, and has hc changeset create/list/show/diff/apply/discard/remove. An applied changeset is on probation like any change. --dry-run shows the ruleset's diff too (docs/design.md, docs/cli.md).
• Bandwidth limits and quotas: rate limits in bytes (--limit 20mbytes/second,over,per-source), per source or per destination; quotas, an allowance of traffic per rule or per address, reset daily, weekly, monthly on a chosen day, or by hand, kept across changes, restarts and reboots (hc quotas, hc rule reset-quota, usage on the rules page). Rules that count traffic are checked before established connections are accepted, so they see every packet. Per-address limits group IPv6 by /64 by default (--group-v4, --group-v6). Meters, byte rates and quotas in an imported ruleset carry over (docs/rules.md).
• Changes checked twice and applied atomically: validation of the whole configuration with stable problem codes (docs/validation.md), then nft -c, then one nft -f transaction that replaces Housecarl's own table, inet housecarl, and nothing else. Dynamic sets' entries and the counters carry across.
• Probation: a change made over the network rolls itself back unless confirmed within two minutes. The web UI and hc confirm their own changes once they reach Housecarl again over a new connection, from the same address (a change that cuts its client off can't, and rolls back); --no-confirm and the "a person confirms each change" setting leave it to hc confirm or the banner; changes through the local socket are kept at once; a restart rolls back what was pending. No rule is forced to keep SSH or the web UI open.
• At boot: the confirmed ruleset is loaded by housecarl-ruleset.service before the network comes up, without housecarld. An empty configuration applies nothing.
• Warnings about the machine: while nftables.service is enabled (it loads /etc/nftables.conf at boot, and flushes every table when stopped), and while the table an import came from still applies.
• The zone matrix (Matrix, hc matrix): what the rules do to new connections between zones and to and from the firewall, worked out from the rules in order, with each pair's exceptions; rules about networks connected to other zones are left out of a pair.
• Connections and tracing: the connections the kernel tracks, with their NAT, and closing them so the rules check them again (Traffic → Connections, hc connections); a rule option, "every packet", for blocks that stop connections already open; and a packet tracer (Traffic → Trace, hc trace) that follows packets through every table's rules and names what accepted or dropped them.
• Hits and the log: packet and byte counters for every rule, NAT rule, built-in and policy; packets logged by rules and policies, read from netlink log group 4171 (hc log -f, the Log page).
• Dynamic sets whose entries expire by themselves, changed through their own API with tokens that may be limited to one set (sets:write:guests).
• Import of an existing nftables ruleset (hc import): rules keep their order, defines name the sets, DNAT becomes port forwards, what can't be translated stays as raw rules, with notes; hc takeover deletes the old table, on probation (docs/import.md). DNAT maps and verdict maps are expanded into one port forward or rule per element.
• The hc CLI, the REST API and the web UI (dashboard, rules per chain with hits and reordering, NAT, zones, sets, services, the log, settings, import, history with undo; the rule dialog keeps the less used parts, such as rate limits, quotas and time windows, behind "+" buttons; each chain's built-ins are listed, with their hits, and switched in a window), with users, roles, scoped API tokens, sessions, the audit log, and the web UI's certificate from Let's Encrypt through Jarl, as in Steward.
• Packaging: Debian packages housecarl and housecarl-cli, a systemd unit whose only privilege is CAP_NET_ADMIN, daily backups.
• The Housecarl logo: a carved Nordic doorway in Jarl's blue, with a simplified version for small sizes, lighter on dark backgrounds; and a HOUSECARL wordmark in Jarl's and Steward's angular letters.