abrown38andClaude Opus 5.5
9d766b9823
The boot unit fails closed: if ruleset.nft doesn't load, it loads ruleset-fallback.nft (render.Fallback), saved beside it from the same configuration: nothing new in from external zones, established, the ICMPv6 IPv6 needs and DHCPv6 replies let in, the inside left alone and masqueraded, and the unit marked failed with a critical message. housecarld replaces it when it applies; status, the dashboard and /healthz say while it is in force. no_external_zone now also says the fallback closes everything without an external zone. The boot ruleset has no flowtable: nftables on Debian 13's kernel refuses one naming a device that doesn't exist yet (ppp0 before PPPoE), and with it the whole file. internal/linkwatch listens to rtnetlink link messages; housecarld applies again when a flowtable device appears or comes back as a new interface (by ifindex), under the engine's lock. docs/flowtable.md: what it does, when to use it and when not, how. GET /healthz reports firewall (applied, unconfigured, fallback, missing), changes on probation and the machine's warnings, with 503 unless in force, read at most every five seconds. Renaming a zone, set or service changes what names it in the same change (one history entry, one undo); dynamic sets keep their names. The importer keeps a chain's head in order: once a would-be built-in stays a rule, the ones after it do too, so the maintainer's ICMPv6 accepts stay behind the invalid drop as written. hc settings set --flowtable none empties the list. make test (nft 1.1.3) and make e2e (242 checks, with VLAN sub-interfaces, the fallback and the flowtable) pass. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.5 KiB
Configuration file
/etc/housecarl/housecarl.yaml says how housecarld runs. The firewall's
configuration (zones, sets, rules, NAT, settings) isn't here; it is in
the database, changed with the CLI, the API or the web UI.
housecarld config --example prints a commented file with the defaults.
Every setting is optional; unknown settings are an error. housecarld
reads the file when it starts.
| Setting | Default | |
|---|---|---|
listen |
["127.0.0.1:8070"] |
addresses of the web UI and API (host:port). Keep them on localhost or a management network, and write an input rule that lets you reach them |
tls.cert_file, tls.key_file |
none | serve HTTPS with this certificate; housecarld rereads it when the file changes, or on systemctl reload housecarl |
tls.acme.* |
off | get the certificate from Let's Encrypt, with Jarl publishing the challenge (certificates.md) |
jarl.server, jarl.token_file (or jarl.token), jarl.ca_cert, jarl.insecure |
none | the Jarl server for the certificate's challenge, and its token (jarl.md) |
ruleset |
/var/lib/housecarl/ruleset.nft |
the confirmed ruleset, which housecarl-ruleset.service loads at boot; its fallback is saved beside it as ruleset-fallback.nft (operations.md). Change both paths in the unit too |
trusted_proxies |
[] |
addresses or prefixes of reverse proxies whose X-Forwarded-For and X-Forwarded-Proto are believed |
socket |
/run/housecarl/housecarl.sock |
the local API socket; "" turns it off |
database |
/var/lib/housecarl/housecarl.db |
the SQLite database: configuration, history, users, audit log |
log.level |
info |
debug (every HTTP request), info, warn or error |
log.format |
text |
text or json |
session.lifetime |
12h |
how long a web UI login lasts |
session.idle_timeout |
2h |
logged out after this long without use |
session.cookie_secure |
auto |
auto (secure over HTTPS), always or never |
backup.dir |
/var/backups/housecarl |
where housecarld backup writes |
backup.retention |
30d |
backups older than this are deleted… |
backup.keep_at_least |
7 |
…keeping at least this many |
stats.enabled |
true |
keep traffic, drops, hits, blocked sources, connections and quotas over time (stats.md) |
stats.database |
/var/lib/housecarl/stats.db |
the statistics' own database; deleting it is safe |
stats.retention.minute, .hour, .day |
7d, 90d, 730d |
how long per-minute, hourly and daily figures are kept |
stats.top_n |
100 |
entries kept per top list, per hour and per day |
Durations are written 15s, 12h or 30d.
The probation's length is a firewall setting, not here: hc settings set --probation 5m. So is counting traffic per device for the statistics:
hc settings set --stats-per-device on.
HTTPS
Over plain HTTP, passwords and tokens cross the network in the clear; housecarld warns when it listens on a non-loopback address without TLS. Let it get its own certificate through Jarl (certificates.md), or give it one:
listen: ["192.168.1.1:8070"]
tls:
cert_file: /etc/housecarl/tls/fullchain.pem
key_file: /etc/housecarl/tls/privkey.pem
Or keep it on 127.0.0.1 behind a reverse proxy that terminates TLS, and
list the proxy in trusted_proxies. With a certificate, the same port
answers HTTPS and redirects plain HTTP to it, except from the firewall
itself.