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>
This commit is contained in:
abrown38andClaude Opus 5.5 committed
1 parent
54beb0bba3
commit
34292eeebb
118 files changed
+22165
-114
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
Executable
+63
@@ -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
|
||||
Executable
+35
@@ -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
|
||||
Executable
+16
@@ -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
|
||||
@@ -0,0 +1,44 @@
|
||||
# Housecarl: one database backup, run daily by housecarl-backup.timer.
|
||||
# Installed as /etc/systemd/system/housecarl-backup.service (see
|
||||
# docs/operations.md#backups). What to keep, and where, is in the backup:
|
||||
# section of /etc/housecarl/housecarl.yaml.
|
||||
[Unit]
|
||||
Description=Housecarl database backup
|
||||
Documentation=file:///usr/local/share/doc/housecarl/docs/operations.md
|
||||
# Nothing to back up before 'housecarld init'.
|
||||
ConditionPathExists=/var/lib/housecarl/housecarl.db
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/local/bin/housecarld --config /etc/housecarl/housecarl.yaml backup
|
||||
User=housecarl
|
||||
Group=housecarl
|
||||
UMask=0077
|
||||
Nice=10
|
||||
IOSchedulingClass=idle
|
||||
|
||||
# If you change backup.dir in housecarl.yaml, allow the new one too:
|
||||
# 'systemctl edit housecarl-backup.service' and add ReadWritePaths=/new/dir.
|
||||
ProtectSystem=strict
|
||||
ReadWritePaths=/var/lib/housecarl -/var/backups/housecarl
|
||||
ProtectHome=yes
|
||||
PrivateTmp=yes
|
||||
PrivateDevices=yes
|
||||
PrivateNetwork=yes
|
||||
NoNewPrivileges=yes
|
||||
CapabilityBoundingSet=
|
||||
ProtectKernelTunables=yes
|
||||
ProtectKernelModules=yes
|
||||
ProtectKernelLogs=yes
|
||||
ProtectControlGroups=yes
|
||||
ProtectClock=yes
|
||||
ProtectHostname=yes
|
||||
RestrictNamespaces=yes
|
||||
RestrictRealtime=yes
|
||||
RestrictSUIDSGID=yes
|
||||
LockPersonality=yes
|
||||
MemoryDenyWriteExecute=yes
|
||||
RestrictAddressFamilies=AF_UNIX
|
||||
SystemCallArchitectures=native
|
||||
SystemCallFilter=@system-service
|
||||
SystemCallErrorNumber=EPERM
|
||||
@@ -0,0 +1,20 @@
|
||||
# Housecarl: runs housecarl-backup.service (a database backup) every day.
|
||||
# Installed as /etc/systemd/system/housecarl-backup.timer. Change the schedule
|
||||
# with 'systemctl edit housecarl-backup.timer', e.g.
|
||||
# [Timer]
|
||||
# OnCalendar=
|
||||
# OnCalendar=*-*-* 02:30
|
||||
# and keep backup.retention in housecarl.yaml above the new interval.
|
||||
[Unit]
|
||||
Description=Daily Housecarl database backup
|
||||
Documentation=file:///usr/local/share/doc/housecarl/docs/operations.md
|
||||
|
||||
[Timer]
|
||||
OnCalendar=daily
|
||||
# Spread the start over an hour, and catch up on a run missed while the
|
||||
# machine was off.
|
||||
RandomizedDelaySec=1h
|
||||
Persistent=true
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
@@ -0,0 +1,21 @@
|
||||
# Housecarl: loads the last confirmed ruleset at boot, before the network
|
||||
# comes up and whether or not housecarld starts.
|
||||
# Installed as /etc/systemd/system/housecarl-ruleset.service.
|
||||
[Unit]
|
||||
Description=Housecarl firewall ruleset
|
||||
Documentation=file:///usr/local/share/doc/housecarl/README.md
|
||||
DefaultDependencies=no
|
||||
Before=network-pre.target shutdown.target
|
||||
Wants=network-pre.target
|
||||
# Debian's nftables.service flushes the whole ruleset: Housecarl's loads after it.
|
||||
After=nftables.service local-fs.target
|
||||
Conflicts=shutdown.target
|
||||
ConditionPathExists=/var/lib/housecarl/ruleset.nft
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
RemainAfterExit=yes
|
||||
ExecStart=/usr/sbin/nft -f /var/lib/housecarl/ruleset.nft
|
||||
|
||||
[Install]
|
||||
WantedBy=sysinit.target
|
||||
@@ -0,0 +1,63 @@
|
||||
# Housecarl: keeps the firewall's nftables ruleset; its REST API and web UI.
|
||||
# Installed as /etc/systemd/system/housecarl.service (see docs/install.md).
|
||||
[Unit]
|
||||
Description=Housecarl firewall manager (with web UI and API)
|
||||
Documentation=file:///usr/local/share/doc/housecarl/README.md
|
||||
# The confirmed ruleset is already in force from housecarl-ruleset.service.
|
||||
After=housecarl-ruleset.service network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=notify
|
||||
NotifyAccess=main
|
||||
ExecStart=/usr/local/bin/housecarld --config /etc/housecarl/housecarl.yaml serve
|
||||
# SIGHUP rereads the TLS certificate.
|
||||
ExecReload=/bin/kill -HUP $MAINPID
|
||||
Restart=on-failure
|
||||
RestartSec=2s
|
||||
|
||||
User=housecarl
|
||||
Group=housecarl
|
||||
UMask=0027
|
||||
|
||||
# /var/lib/housecarl: the database and the confirmed ruleset (ruleset.nft).
|
||||
StateDirectory=housecarl
|
||||
StateDirectoryMode=0750
|
||||
ConfigurationDirectory=housecarl
|
||||
ConfigurationDirectoryMode=0750
|
||||
# /run/housecarl: the local API socket (housecarl.sock), for root and the
|
||||
# housecarl user.
|
||||
RuntimeDirectory=housecarl
|
||||
RuntimeDirectoryMode=0750
|
||||
|
||||
# Sandboxing: housecarld writes only its own state.
|
||||
ProtectSystem=strict
|
||||
ProtectHome=yes
|
||||
PrivateTmp=yes
|
||||
PrivateDevices=yes
|
||||
NoNewPrivileges=yes
|
||||
# The only privilege housecarld gets: changing nftables (it runs nft) and
|
||||
# reading logged packets (nfnetlink_log), both CAP_NET_ADMIN.
|
||||
CapabilityBoundingSet=CAP_NET_ADMIN
|
||||
AmbientCapabilities=CAP_NET_ADMIN
|
||||
ProtectKernelTunables=yes
|
||||
ProtectKernelModules=yes
|
||||
ProtectKernelLogs=yes
|
||||
ProtectControlGroups=yes
|
||||
ProtectClock=yes
|
||||
ProtectHostname=yes
|
||||
RestrictNamespaces=yes
|
||||
RestrictRealtime=yes
|
||||
RestrictSUIDSGID=yes
|
||||
LockPersonality=yes
|
||||
MemoryDenyWriteExecute=yes
|
||||
# AF_NETLINK: nftables, logged packets, the interfaces and their addresses.
|
||||
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
|
||||
SystemCallArchitectures=native
|
||||
SystemCallFilter=@system-service
|
||||
SystemCallErrorNumber=EPERM
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
# 'systemctl restart housecarld' works too (the daemon's binary is housecarld).
|
||||
Alias=housecarld.service
|
||||
@@ -0,0 +1,2 @@
|
||||
# Housecarl's system user (installed as /usr/lib/sysusers.d/housecarl.conf).
|
||||
u housecarl - "Housecarl firewall manager" /var/lib/housecarl
|
||||
@@ -0,0 +1,8 @@
|
||||
# Directories Housecarl needs (installed as /usr/lib/tmpfiles.d/housecarl.conf).
|
||||
# Apply with: systemd-tmpfiles --create housecarl.conf
|
||||
#
|
||||
# Type Path Mode User Group
|
||||
d /etc/housecarl 0750 root housecarl
|
||||
d /var/lib/housecarl 0750 housecarl housecarl
|
||||
# Database backups (housecarl-backup.timer; backup.dir in housecarl.yaml).
|
||||
d /var/backups/housecarl 0700 housecarl housecarl
|
||||
Reference in new issue
Block a user