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>

docs/install.md

@@ -0,0 +1,138 @@
+# Installing Housecarl
+
+Housecarl runs on Linux with nftables 1.0 or newer. It is made for and
+tested on Debian 13 (nftables 1.1.3). The CLI also runs on macOS and
+Windows.
+
+## From the package registry
+
+The release workflow publishes Debian packages to the Gitea registry,
+`stable` for releases and `testing` for release candidates. Jarl's and
+Steward's packages come from the same registry. If apt already has it,
+`sudo apt install housecarl` is all it takes. Otherwise add it:
+
+```sh
+sudo install -d /etc/apt/keyrings
+sudo curl -fsSL https://gitea.adbraun.lol/api/packages/adam/debian/repository.key -o /etc/apt/keyrings/gitea-adam.asc
+echo "deb [signed-by=/etc/apt/keyrings/gitea-adam.asc] https://gitea.adbraun.lol/api/packages/adam/debian stable main" \
+  | sudo tee /etc/apt/sources.list.d/gitea-adam.list
+sudo apt update
+sudo apt install housecarl
+```
+
+For release candidates too, add the `testing` distribution: the same
+`deb` line with `testing` instead of `stable`.
+
+There are two packages:
+
+* **`housecarl`** is the server: `/usr/bin/housecarld`, the systemd units
+  `housecarl.service`, `housecarl-ruleset.service` (the ruleset at boot),
+  `housecarl-backup.service` and `housecarl-backup.timer`, and the
+  `housecarl` user and directories. It creates
+  `/etc/housecarl/housecarl.yaml` on the first install and never touches
+  it again. It depends on `housecarl-cli` and `nftables`.
+* **`housecarl-cli`** is the CLI, `/usr/bin/hc`. It can be installed
+  alone on any machine to manage Housecarl remotely.
+
+Installing changes nothing in the firewall: housecarld applies a ruleset
+only once it has a configuration.
+
+The release page also has `.deb` files, tarballs and the CLI for Linux,
+macOS and Windows.
+
+## From source
+
+```sh
+make                        # bin/housecarld, bin/hc (Go, as in go.mod)
+sudo make install           # /usr/local/bin, units in /etc/systemd/system
+sudo systemd-sysusers housecarl.conf && sudo systemd-tmpfiles --create housecarl.conf
+sudo chgrp housecarl /etc/housecarl /etc/housecarl/housecarl.yaml && sudo systemctl daemon-reload
+```
+
+`make deb` builds the packages (`DEB_ARCH=arm64` for another architecture).
+
+## First steps
+
+Do this from a console, or over SSH with a way back in if it goes wrong:
+you are changing the firewall you are connected through.
+
+1. **Settings** are in `/etc/housecarl/housecarl.yaml`
+   ([configuration.md](configuration.md)). By default the web UI and API
+   listen on `127.0.0.1:8070`. To reach them from your network, add an
+   address there, ideally with TLS or behind a TLS reverse proxy.
+2. **Create the database and the first administrator:**
+
+   ```sh
+   sudo -u housecarl housecarld init
+   ```
+
+   It asks for the administrator's name (`admin` if you just press Enter;
+   your own name is better) and password.
+3. **Start Housecarl:**
+
+   ```sh
+   sudo systemctl enable --now housecarl
+   ```
+
+   Until it has a configuration, housecarld applies nothing: the machine
+   stays as open (or as closed) as it was.
+4. **Import your ruleset**, if you have one ([import.md](import.md)):
+
+   ```sh
+   sudo hc import --defines /etc/nftables.conf -n      # look
+   sudo hc import --defines /etc/nftables.conf         # import
+   sudo hc takeover "inet main"
+   sudo systemctl disable nftables.service
+   ```
+
+   **Or start from scratch**, through the local socket (no probation).
+   The first change puts the ruleset in force, and the input and forward
+   policies drop what no rule accepts, so let yourself in first:
+
+   ```sh
+   sudo hc set add admins 10.0.10.0/24
+   sudo hc rule add input --from admins --service ssh
+   sudo hc rule add input --from admins --service tcp/8070 --comment "Housecarl"
+   sudo hc zone add wan --interface ppp0 --external
+   sudo hc zone add lan --interface enp2s0
+   sudo hc rule add input --in lan --service dns --service dhcp
+   sudo hc rule add forward --in lan --out wan
+   sudo hc snat add --out wan
+   sudo hc settings set --builtin mss_clamp=on --own-prefix 2001:db8:7f3d::/48
+   sudo hc status
+   ```
+
+   Housecarl doesn't add a rule that keeps SSH or the web UI open: you
+   write it. Connections already open (your SSH session) carry on, since
+   established connections are accepted.
+5. **Open the web UI** on an address in `listen`, and log in.
+
+## From another machine
+
+Install `housecarl-cli`, make a token, and set the server:
+
+```sh
+sudo hc token create laptop               # on the firewall; prints the token once
+hc config set server https://fw.example.com:8070
+hc config set token                       # paste it
+hc status
+```
+
+Changes from there are on probation: `hc confirm` keeps them.
+
+## Upgrading
+
+`apt upgrade` restarts a running housecarld, which applies the ruleset
+again (counters keep counting) and upgrades its database when it starts.
+The firewall stays up during the upgrade: the ruleset belongs to the
+kernel, not to housecarld. Take a backup first if you like
+(`sudo -u housecarl housecarld backup`); the daily timer keeps 30 days of
+them.
+
+## Removing
+
+`apt remove housecarl` stops housecarld and disables the boot unit. The
+ruleset stays in force until the next boot, or until you delete it:
+`sudo nft delete table inet housecarl`. A purge keeps the database and
+the backups; remove `/var/lib/housecarl` and `/var/backups/housecarl` by
+hand if you no longer need them.