-
Housecarl v0.1.0-rc.6
Pre-Releaserelease / release (push) Successful in 1m0sadam released this
2026-10-20 17:29:02 +00:00 | -14 commits to main since this releaseThe 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 likeincusbr*; 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 IDorHOUSECARL_CHANGESET, and hashc changeset create/list/show/diff/apply/discard/remove. An applied
changeset is on probation like any change.--dry-runshows 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),
thennft -c, then onenft -ftransaction 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 andhcconfirm 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-confirmand the "a person confirms each change" setting leave it
tohc confirmor 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.servicebefore the network comes up, without
housecarld. An empty configuration applies nothing. - Warnings about the machine: while
nftables.serviceis enabled
(it loads/etc/nftables.confat 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
hcCLI, 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
housecarlandhousecarl-cli, a
systemd unit whose only privilege isCAP_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.
Downloads
- Zones, address sets and services: interfaces grouped by what they