adam/housecarl
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 34 Wiki Activity

34 Releases 34 Tags

RSS Feed
  • v0.1.0-rc.3 d25e12995e
    Compare

    Housecarl v0.1.0-rc.3
    release / release (push) Successful in 57s
    Details
    Pre-Release

    adam released this 2026-10-19 12:24:50 +00:00 | -8 commits to main since this release

    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; 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.
    • 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), 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.
    Downloads