abrown38andClaude Opus 5.5
2880f7ddc9
Changesets, as in Jarl: configuration changes are operations that can be staged in a changeset, checked as they are added (validation and nft -c), reviewed with the diff of the ruleset, and applied together as one history entry, then on probation like any change made over the network. The web UI collects edits for review by default (pending rows, a bar with Review and Apply now, a Changes page, a switch for live edits); hc stages with -C ID or HOUSECARL_CHANGESET (checked like JARL_CHANGESET) and has hc changeset create/list/show/diff/apply/discard/remove. Undo, import and takeover refuse a changeset. --dry-run shows the ruleset's diff. Bandwidth and quotas: rate limits in bytes, per source or destination; quotas per rule or per address that reset daily, weekly, monthly on a day, or by hand, with their usage carried across reloads, saved for reboots, shown by hc quotas and on the rules page, and reset with hc rule reset-quota. Rules that count traffic are checked before established connections are accepted (so they see every packet) and can't accept. Per-address limits group IPv6 by /64 by default (--group-v4/-v6). Per-source rate meters use update. The importer turns meters, byte rates and quotas into these fields. The examples in the web UI, hc's help and the docs use documentation addresses and generic names instead of the maintainer's network. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
53 lines
2.8 KiB
Markdown
53 lines
2.8 KiB
Markdown
# 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](certificates.md#settings)) |
|
|
| `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](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](certificates.md)),
|
|
or give it one:
|
|
|
|
```yaml
|
|
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.
|