# 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: ["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.