abrown38andClaude Opus 5.5
34292eeebb
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>
2.8 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 |
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 |
Durations are written 15s, 12h or 30d.
The probation's length is a firewall setting, not here: hc settings set --probation 5m.
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: ["10.0.10.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.