jarl/docs/configuration.md

# jarld configuration (`/etc/jarl/jarl.yaml`)

jarld reads `/etc/jarl/jarl.yaml` (or the file given with `-c/--config`,
which every jarld subcommand accepts). Every setting is optional. The
defaults suit Debian/Ubuntu with BIND 9.20. Unknown keys are an error, so
typos don't go unnoticed.

```sh
jarld config --example    # a commented example file with every setting
jarld config              # the effective configuration (file + defaults)
```

The CLI has its own small configuration file, described in [cli.md](cli.md).

## Settings

### Web UI and API

| Key | Default | Meaning |
|-----|---------|---------|
| `listen` | `["127.0.0.1:8053"]` | Addresses to listen on (`host:port`, several allowed). Keep these on localhost and management networks. |
| `tls.cert_file`, `tls.key_file` | (empty: plain HTTP) | PEM certificate chain and key. Both or neither. The files are rechecked every 10 minutes and on SIGHUP (`systemctl reload jarl`), so renewed certificates are used without a restart. |
| `trusted_proxies` | `[]` | Addresses or prefixes of reverse proxies whose `X-Forwarded-For` and `X-Forwarded-Proto` headers are believed. Needed for correct client IPs in the audit log and for rate limiting behind a proxy. |
| `session.lifetime` | `12h` | A web session ends this long after login... |
| `session.idle_timeout` | `2h` | ...or after this long without requests. |
| `session.cookie_secure` | `auto` | `auto` sets the cookie's Secure flag when the request came over HTTPS (directly or via a trusted proxy); `always` / `never` force it. |

Durations accept Go syntax (`90s`, `15m`, `12h`) and days (`30d`).

### Storage

| Key | Default | Meaning |
|-----|---------|---------|
| `database` | `/var/lib/jarl/jarl.db` | SQLite database: configuration, users, tokens, history, audit log. |
| `staging_dir` | `/var/lib/jarl/staging` | Scratch space where candidate configurations are rendered and checked with named-checkconf before they are installed. |
| `audit.retention_days` | `0` | Delete audit events older than this many days (0 keeps them forever). Changeset history is kept regardless. |

### Logging

| Key | Default | Meaning |
|-----|---------|---------|
| `log.level` | `info` | `debug`, `info`, `warn` or `error`. |
| `log.format` | `text` | `text` or `json`. Under systemd both go to the journal (`journalctl -u jarl`). |

Audit events are logged as `msg=audit` lines as well as stored in the
database.

### BIND

| Key | Default | Meaning |
|-----|---------|---------|
| `bind.main_config` | `/etc/bind/named.conf` | The file named loads. `jarld import` reads it, and `jarld adopt` replaces it with an include of Jarl's configuration. |
| `bind.config_dir` | `/etc/bind/jarl` | Where Jarl writes `named.conf` and `keys.conf`. Must be readable by named. |
| `bind.zone_dir` | `/var/lib/bind/jarl` | Primary zone files (`<view>/<zone>.zone`). named may write journals here. |
| `bind.cache_dir` | `/var/cache/bind/jarl` | Where named stores secondary, stub and mirror zones. |
| `bind.file_group` | `bind` | Group given to generated files and directories so named can read them. Empty leaves the group alone. |
| `bind.named_checkconf` | `/usr/bin/named-checkconf` | Used to check every candidate configuration (`-z` also loads the zones). |
| `bind.named_checkzone` | `/usr/bin/named-checkzone` | Used to check zone files. |
| `bind.rndc` | `/usr/sbin/rndc` | Used to reconfigure and reload named and to read zone serials. |
| `bind.rndc_args` | `[]` | Extra rndc arguments, e.g. `["-k", "/etc/bind/rndc.key", "-s", "127.0.0.1", "-p", "953"]`. Debian's rndc finds `/etc/bind/rndc.key` by itself. |
| `bind.reload_timeout` | `15s` | How long to wait for named to load changed zones (checked with `rndc zonestatus`) before the change is rolled back. |
| `bind.no_reload` | `false` | Write files but never run rndc. Use it when named runs on another host or for testing. Changes are then not verified against a running named. |

The three directories must exist and be writable by the `jarl` user. The
tmpfiles.d entry creates them, and the systemd unit only allows writes
there (`ReadWritePaths`). If you change them, update both
`/usr/lib/tmpfiles.d/jarl.conf` and the unit (`systemctl edit jarl`):

```ini
[Service]
ReadWritePaths=/srv/bind/jarl /srv/bind/zones
```

## Example: management network with TLS

```yaml
listen:
  - "127.0.0.1:8053"
  - "192.168.10.2:8053"
tls:
  cert_file: /etc/jarl/tls/fullchain.pem
  key_file: /etc/jarl/tls/privkey.pem
log:
  level: info
audit:
  retention_days: 730
```

## Example: behind nginx

```yaml
listen: ["127.0.0.1:8053"]
trusted_proxies: ["127.0.0.1"]
```

```nginx
location / {
    proxy_pass http://127.0.0.1:8053;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 300s;   # applying a large changeset can take a while
}
```