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.

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.

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.

Query statistics

The stats: section turns on query statistics (off by default). See stats.md for every setting and what it changes in named's configuration. Changing it takes effect when jarld restarts.

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):

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

Example: management network with TLS

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

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

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
}