abrown38andClaude Opus 5.5
0b2159b1a4
jarl token rotate, a Rotate button in the web UI and
POST /api/v1/tokens/{id}/rotate give a token a new secret while it keeps
its ID, name, user and grants. The old secret stops at once or after a
grace period of up to 7 days, during which jarld logs who still uses it.
A token that expires gets its lifetime again. --save writes the new
secret where the CLI got the old one (its configuration or --token @FILE),
--write FILE to any file, and --current picks the token the CLI runs
with, so a restricted token can renew itself. A restricted token can't
rotate a wider token of its user.
Also fixes token create --save for named servers, and future times
(token expiry) shown as "just now" in the web UI.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
156 lines
7.5 KiB
Markdown
156 lines
7.5 KiB
Markdown
<p align="center"><img src="internal/web/static/assets/logo.svg" width="120" alt="Jarl logo: a Viking jarl in a spear-pointed crown holding a DNS tree"></p>
|
|
|
|
# Jarl
|
|
|
|
*A Jarl rules a Hold; this one rules your zones.*
|
|
|
|
Jarl manages a BIND 9 (named) server: zones, records of every type, views,
|
|
ACLs, TSIG keys and any named.conf option. It has a web UI, a REST API and
|
|
a command line client. All three go through the same validated, audited,
|
|
all-or-nothing change pipeline, and nothing reaches named before BIND's own
|
|
checkers have accepted it.
|
|
|
|
```
|
|
$ jarl record add adbraun.lol nas A 192.168.1.20 --ptr
|
|
add nas.adbraun.lol. IN A 192.168.1.20
|
|
add 20.1.168.192.in-addr.arpa. IN PTR nas.adbraun.lol.
|
|
zone 1.168.192.in-addr.arpa serial 2026100700 -> 2026100701
|
|
zone adbraun.lol serial 2026100701 -> 2026100702
|
|
applied (changeset 12)
|
|
|
|
$ jarl record add adbraun.lol www A 192.168.1.99
|
|
error: www.adbraun.lol has a CNAME, so it can't have any other records (found A); a CNAME must be the only record at its name (RFC 1034) [zone adbraun.lol]
|
|
```
|
|
|
|
## Features
|
|
|
|
* **Everything in one place**: primary, secondary, forward, stub, mirror,
|
|
hint, redirect and in-view zones, reverse zones from a CIDR, split DNS with
|
|
views, ACLs, TSIG keys, and every BIND 9.20 option at server, view, zone
|
|
and top level, with the ARM's description and grammar built in.
|
|
* **Safe changes.** Every change is validated as a whole (CNAME rules,
|
|
glue, delegations, RRset TTLs, references, option syntax, open-resolver
|
|
and open-transfer lints), checked with `named-checkconf -z`, installed
|
|
atomically, reloaded, and verified with `rndc zonestatus`. If named
|
|
doesn't load it, the previous files are put back.
|
|
* **Changesets**: apply edits one at a time, or bundle them, review the
|
|
diff, and apply them together. Every applied changeset can be reverted.
|
|
Serials are bumped automatically.
|
|
* **Users and API tokens with granular permissions**, e.g. a token that may
|
|
only write `_acme-challenge` TXT records in one zone. Tokens can be
|
|
rotated (a new secret, same grants), with an optional grace period.
|
|
Passwords use argon2id, sessions have CSRF protection, logins are rate
|
|
limited.
|
|
* **Audit log** of every login, change and token, with user, token, IP and
|
|
outcome.
|
|
* **Query statistics** (optional, off by default): queries over time,
|
|
busiest hours of the week, top names and clients, NXDOMAIN and refused
|
|
queries, record types, cache hit rate. Shown in the web UI and the CLI,
|
|
and exportable as JSON. Stored as aggregates in a separate database with
|
|
retention you set.
|
|
* **Let's Encrypt DNS-01** built in: `jarl acme` plus certbot, acme.sh and lego
|
|
hooks, an HTTPS-only endpoint for lego's and Traefik's `httpreq` provider,
|
|
and CNAME delegation to a dedicated ACME zone.
|
|
* **Adopts an existing server**: imports named.conf and zone files
|
|
(comments included), then switches named over with an automatic
|
|
fallback.
|
|
* One static Go binary for the daemon (web UI embedded, SQLite built in) and
|
|
one for the CLI, run by a sandboxed systemd service as an unprivileged
|
|
user.
|
|
|
|
## Quick start
|
|
|
|
On a Debian/Ubuntu BIND 9.20 server ([install.md](docs/install.md) has the
|
|
details):
|
|
|
|
```sh
|
|
make && sudo make install
|
|
sudo systemd-sysusers jarl.conf && sudo systemd-tmpfiles --create jarl.conf
|
|
sudo chgrp jarl /etc/jarl/jarl.yaml
|
|
sudo -u jarl jarld init --token # first admin + a CLI token
|
|
sudo -u jarl jarld import # read the current named.conf and zones
|
|
sudo jarld adopt # switch named over (keeps a backup, rolls back on failure)
|
|
sudo systemctl enable --now jarl
|
|
|
|
jarl config set server http://127.0.0.1:8053
|
|
jarl config set token # paste the token from 'jarld init'
|
|
jarl status
|
|
```
|
|
|
|
Then open the web UI at `http://127.0.0.1:8053/`, or set `listen` and `tls`
|
|
in `/etc/jarl/jarl.yaml` to reach it from your management network.
|
|
|
|
## Documentation
|
|
|
|
| | |
|
|
|-|-|
|
|
| [docs/concepts.md](docs/concepts.md) | How Jarl works: source of truth, changesets, the apply pipeline, authentication. Read this first |
|
|
| [docs/install.md](docs/install.md) | Installing, importing and adopting an existing server, TLS, upgrading |
|
|
| [docs/configuration.md](docs/configuration.md) | `/etc/jarl/jarl.yaml` reference |
|
|
| [docs/cli.md](docs/cli.md) | The `jarl` command line client |
|
|
| [docs/api.md](docs/api.md) | REST API reference |
|
|
| [docs/permissions.md](docs/permissions.md) | Users, tokens, grants and roles |
|
|
| [docs/views.md](docs/views.md) | Split DNS: adding views to a server that has none |
|
|
| [docs/acme.md](docs/acme.md) | Let's Encrypt DNS-01 with certbot, acme.sh, lego and Traefik |
|
|
| [docs/stats.md](docs/stats.md) | Query statistics: enabling, what is collected, retention |
|
|
| [docs/validation.md](docs/validation.md) | Every check Jarl makes |
|
|
| [docs/operations.md](docs/operations.md) | Backups, drift, failures, recovery, monitoring |
|
|
| [docs/development.md](docs/development.md) | Code layout, tests against real BIND, conventions |
|
|
| [CHANGELOG.md](CHANGELOG.md) | Changes per release |
|
|
|
|
## The web UI
|
|
|
|
The UI is built for getting things done rather than for looks. It has
|
|
these pages:
|
|
|
|
* **Dashboard**: named status, adoption, drift, recent changes, open
|
|
problems.
|
|
* **Statistics** (when enabled): queries over time, failed answers, a
|
|
weekday x hour heatmap, top names and clients, and breakdowns. Every chart
|
|
has a table view.
|
|
* **Zones**: list, create (choose a domain or a network, and the dialog shows
|
|
the exact zone name it will create and warns about likely mistakes;
|
|
fields adapt to the zone type), per-zone records
|
|
with inline editing, type-specific hints and a preview of the exact record
|
|
that will be added (reverse zones take addresses and suggest host names), settings (SOA, TTL, serial
|
|
policy, view), options, the generated zone file, and pasting a zone file
|
|
to merge or replace records.
|
|
* **Views, ACLs, TSIG keys, Server options**: wherever an address match list
|
|
is entered, the existing ACLs and keys are offered and unknown names are
|
|
flagged. The options editor knows every
|
|
BIND 9.20 statement for the scope and shows its description, grammar and
|
|
a value field that fits it.
|
|
* **Changes**: pending edits with the diff, named-checkconf output and
|
|
problems, applied as one changeset. History lists applied changesets with
|
|
their diffs and a revert button.
|
|
* **Audit, Users, Account** (password, API tokens) and **Search**.
|
|
|
|
By default, edits are collected as pending changes. Pending rows are shown
|
|
inline (green = new, yellow = changed, struck out = deleted) until you
|
|
review and apply them. Switch on "Apply edits immediately" to skip the
|
|
review step.
|
|
|
|
## Requirements
|
|
|
|
* BIND 9.20, with `named-checkconf`, `named-checkzone` and `rndc`. The
|
|
option catalog follows 9.20. 9.18 will probably work, because
|
|
named-checkconf still checks every change, but it is untested.
|
|
* Linux with systemd for the packaged service. Defaults match
|
|
Debian/Ubuntu, and other layouts are configurable.
|
|
* Go 1.27+ to build.
|
|
|
|
## Status
|
|
|
|
Version 0.1.0, the first release. It is feature-complete for one server's
|
|
configuration. DNSSEC signing and managing several servers are not handled
|
|
yet ([concepts.md](docs/concepts.md#what-jarl-deliberately-doesnt-do-yet)).
|
|
|
|
## Credits
|
|
|
|
The "Jarl" name in the web UI's header uses [Cinzel](https://github.com/NDISCOVER/Cinzel) Bold
|
|
by the Cinzel Project Authors, under the SIL Open Font License 1.1
|
|
(`internal/web/static/assets/fonts/Cinzel-OFL.txt`). The logo
|
|
(`assets/logo.svg`, and `assets/logo-white.svg` for dark backgrounds) is part
|
|
of Jarl: a Viking ruler drawn like a woodcut, whose crown holds a DNS tree
|
|
(a root node with its branches). It is generated by `scripts/logo.py`.
|