Build Housecarl 0.1.0: the nftables firewall manager

Zones, address sets (IPv4 and IPv6 mixed, dynamic sets with timeouts) and
services, ordered rules in the early, input, forward and output chains,
port forwards with hairpin NAT and IPv6 pinholes, source NAT, redirects,
and switchable built-ins (loopback, conntrack, ICMPv6, antispoofing, MSS
clamping, DHCPv6 client, flowtable). Every change is validated, checked
with nft -c and applied in one transaction to Housecarl's own table,
inet housecarl; changes made over the network roll back unless
confirmed, and the confirmed ruleset is loaded at boot by
housecarl-ruleset.service. An empty configuration applies nothing.

Also: hit counters and the drop log (nflog), 'hc import' of an existing
nftables ruleset and 'hc takeover', the hc CLI, the REST API and the web
UI, users, scoped tokens (sets:write:NAME), the audit log, the web UI's
certificate through Jarl, Debian packages, docs, unit tests with real
nft 1.1.3, and an e2e test with real traffic (71 checks).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

deploy/debian/control-housecarl-cli.in

@@ -0,0 +1,17 @@
+Package: housecarl-cli
+Version: @VERSION@
+Architecture: @ARCH@
+Maintainer: @MAINTAINER@
+Installed-Size: @SIZE@
+Section: net
+Priority: optional
+Description: command line client for Housecarl, the firewall manager
+ hc is the command line client for Housecarl servers (housecarld): zones,
+ address sets, services, rules, port forwards, source NAT and redirects,
+ counters and the drop log, the history of changes with undo and the
+ confirmation of changes on probation, users and tokens, and importing an
+ nftables ruleset. It talks to housecarld's REST API with an API token,
+ or, on the firewall itself, to housecarld's local socket.
+ .
+ Install this package alone to manage Housecarl from another machine; the
+ housecarl package (the server) depends on it.

deploy/debian/control-housecarl.in

@@ -0,0 +1,22 @@
+Package: housecarl
+Version: @VERSION@
+Architecture: @ARCH@
+Maintainer: @MAINTAINER@
+Installed-Size: @SIZE@
+Depends: systemd, nftables, housecarl-cli (= @VERSION@)
+Section: net
+Priority: optional
+Description: nftables firewall manager with a web UI, a REST API and a CLI
+ Housecarl keeps a Linux firewall's nftables ruleset: zones, address sets,
+ services, ordered rules, port forwards with hairpin NAT and IPv6
+ pinholes, source NAT and redirects, IPv4 and IPv6 together, in its own
+ table (inet housecarl). It is configured through a web UI, a REST API and
+ the hc command line client. Every change is validated as a whole and
+ checked by nftables before it is applied in one transaction, recorded in
+ a history where it can be undone, and audited. A change made over the
+ network is rolled back unless confirmed. It can import an existing
+ nftables ruleset.
+ .
+ This package is the server: housecarld (as the systemd service housecarl),
+ the boot unit housecarl-ruleset and the daily backup timer. The hc CLI
+ comes from housecarl-cli.

deploy/debian/postinst

@@ -0,0 +1,63 @@
+#!/bin/sh
+# Housecarl: runs after the package's files are in place.
+set -e
+
+if [ "$1" = configure ]; then
+	# The housecarl system user and Housecarl's directories: /etc/housecarl,
+	# /var/lib/housecarl and /var/backups/housecarl.
+	systemd-sysusers housecarl.conf
+	systemd-tmpfiles --create housecarl.conf || true
+
+	# An example configuration on the first install; an existing one is
+	# never touched.
+	if [ ! -e /etc/housecarl/housecarl.yaml ]; then
+		/usr/bin/housecarld config --example > /etc/housecarl/housecarl.yaml.dpkg-new
+		chown root:housecarl /etc/housecarl/housecarl.yaml.dpkg-new
+		chmod 0640 /etc/housecarl/housecarl.yaml.dpkg-new
+		mv /etc/housecarl/housecarl.yaml.dpkg-new /etc/housecarl/housecarl.yaml
+	fi
+
+	# The daily database backup (housecarl-backup.timer) is on by default. An
+	# administrator's 'systemctl disable housecarl-backup.timer' is remembered
+	# by deb-systemd-helper and kept across upgrades. Before 'housecarld init'
+	# the backup skips itself (there is no database yet).
+	if command -v deb-systemd-helper >/dev/null 2>&1; then
+		deb-systemd-helper unmask housecarl-backup.timer >/dev/null || true
+		if deb-systemd-helper --quiet was-enabled housecarl-backup.timer; then
+			deb-systemd-helper enable housecarl-backup.timer >/dev/null || true
+		else
+			deb-systemd-helper update-state housecarl-backup.timer >/dev/null || true
+		fi
+	elif [ -z "$2" ] && [ -d /run/systemd/system ]; then
+		systemctl enable housecarl-backup.timer >/dev/null 2>&1 || true
+	fi
+
+	# The boot unit loads the last confirmed ruleset before the network comes
+	# up; it does nothing until housecarld has saved one.
+	if [ -z "$2" ] && [ -d /run/systemd/system ]; then
+		systemctl enable housecarl-ruleset.service >/dev/null 2>&1 || true
+	fi
+
+	if [ -d /run/systemd/system ]; then
+		systemctl daemon-reload || true
+		if systemctl is-enabled --quiet housecarl-backup.timer 2>/dev/null; then
+			systemctl start housecarl-backup.timer || true
+		fi
+		# An upgrade restarts a running housecarld (its database is upgraded
+		# when it starts). A first install starts nothing: Housecarl needs
+		# 'housecarld init' first.
+		if [ -n "$2" ] && systemctl is-active --quiet housecarl.service; then
+			systemctl restart housecarl.service || echo "housecarl: restarting housecarld failed; see 'journalctl -u housecarl'" >&2
+		fi
+	fi
+
+	if [ -z "$2" ]; then
+		echo "Housecarl is installed. Next: create the database and start it, as described"
+		echo "in /usr/share/doc/housecarl/docs/install.md:"
+		echo "  sudo -u housecarl housecarld init && sudo systemctl enable --now housecarl"
+		echo "To bring your current nftables ruleset over: sudo hc import --defines /etc/nftables.conf -n"
+		echo "(docs/import.md). Housecarl only writes its own table, inet housecarl."
+	fi
+fi
+
+exit 0

deploy/debian/postrm

@@ -0,0 +1,35 @@
+#!/bin/sh
+# Housecarl: runs after the package's files are removed.
+set -e
+
+case "$1" in
+remove|purge)
+	if [ -d /run/systemd/system ]; then
+		systemctl daemon-reload || true
+	fi
+	;;
+esac
+
+# The backup timer's enabled state (see postinst): masked while the
+# package is removed, forgotten on purge.
+if command -v deb-systemd-helper >/dev/null 2>&1; then
+	case "$1" in
+	remove)
+		deb-systemd-helper mask housecarl-backup.timer >/dev/null || true
+		;;
+	purge)
+		deb-systemd-helper purge housecarl-backup.timer >/dev/null || true
+		deb-systemd-helper unmask housecarl-backup.timer >/dev/null || true
+		;;
+	esac
+fi
+
+# Even a purge keeps Housecarl's data: the database in /var/lib/housecarl holds
+# the configuration and its history. Remove it by hand when you no longer
+# need it.
+if [ "$1" = purge ]; then
+	echo "housecarl: kept /etc/housecarl, /var/lib/housecarl and /var/backups/housecarl;"
+	echo "remove them by hand if unused."
+fi
+
+exit 0

deploy/debian/prerm

@@ -0,0 +1,16 @@
+#!/bin/sh
+# Housecarl: runs before the package's files are removed (also on upgrades).
+set -e
+
+# On removal (not on upgrade) stop housecarld and the backup timer and remove
+# the boot-time links (postrm deals with the timer's). The ruleset in force
+# stays until the next boot; then the machine has no Housecarl table.
+if [ "$1" = remove ] && [ -d /run/systemd/system ]; then
+	systemctl stop housecarl.service housecarl-backup.timer housecarl-backup.service 2>/dev/null || true
+	systemctl disable housecarl.service housecarl-ruleset.service 2>/dev/null || true
+	if ! command -v deb-systemd-helper >/dev/null 2>&1; then
+		systemctl disable housecarl-backup.timer 2>/dev/null || true
+	fi
+fi
+
+exit 0