adam/jarl
1
0 Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases 34 Wiki Activity

Linked zones: shared records kept in step across views

Browse Source 
Zones of the same name in different views can be linked. Shared records
are kept in step: a change in one view reaches the others in the same
changeset, as explicit operations, so the diff, permission checks,
history and undo cover every view. Records local to a view override the
shared records of that name and type there; removing the override brings
the shared ones back, and sharing a view's version makes it every view's.
Each zone keeps its own options, serial and file.

Linking existing zones changes no answer: what is the same everywhere
becomes shared, the rest stays local. Unlinking keeps every record, all
local. ACME challenges are written once per link, and --view all changes
a link once. jarl zone link/unlink, zone create --link-with, record
--local/--shared, LINK column, web UI controls, POST /zones/{zone}/link
and /unlink, validation checks linked_*, store migration 11, docs and
e2e.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
adamandClaude Opus 5.5 committed 2026-10-12 15:53:58 +01:00
1 parent 6313fa51f8
commit 057433c198
31 files changed
+1729 -55
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/api.md
+15
View File
@@ -342,6 +342,21 @@ registrar_error`.
### Records
In a linked zone ([views.md](views.md#linked-zones)), records carry
`shared_id` and `linked` (`shared` or `local`). Creating, updating
(`PATCH /records/{id}`) and setting (`PUT .../rrsets/...`) take `"local":
true` (this view only, an override) or `false` (shared; on an update or a
set it makes this view's version every view's). Zones carry `link_group`
and `linked_with` (the other views).
| Method | Path | Body |
|--------|------|------|
| POST | `/zones/{zone}/link` | `{"with": ["external"]}` (default: every view with that zone). Names and types that are the same everywhere become shared, the rest stay local |
| POST | `/zones/{zone}/unlink` | Takes the zone out of its link; its records stay, all local |
`POST /zones` takes `"link_with": "VIEW"` to create a zone linked with
that view's zone of the same name.
| Method | Path | Body / query |
|--------|------|--------------|
| GET | `/zones/{zone}/records` | `?name=`, `?type=`, `?q=`, `?disabled=1` (only disabled records) or `0` (only enabled ones) |
docs/cli.md
+12
View File
@@ -211,6 +211,18 @@ router, answers for the rest of the /24. IPv4 networks smaller than a /24
are deleted. Try it with `--dry-run` first. `--option "NAME VALUE"` on
`zone create` sets any zone option in the same step.
Linked zones ([views.md](views.md#linked-zones)) keep their shared
records in step across views:
```sh
jarl zone link adbraun.lol --view internal --with external
jarl zone create adbraun.lol --view vps --link-with external
jarl zone unlink adbraun.lol --view vps
jarl record add adbraun.lol nas A 10.0.10.20 --view internal --local # this view only
jarl record set adbraun.lol www A 10.0.10.5 --view internal --local # override the shared www A here
jarl record update 1234 --local | --shared
```
When a zone exists in several views, add `--view NAME` to commands that
name it.
docs/validation.md
+14
View File
@@ -104,6 +104,20 @@ applied.
| `dnssec_old_keys` | info | Signing a zone whose key directory still has old keys |
| `serial_not_higher` | error | An explicit serial on a signed zone must be above the one named has loaded (automatic serials are raised by themselves) |
## Linked zones
See [views.md](views.md#linked-zones). Jarl keeps linked zones in step
itself, so these only show when something got past it (a change staged
before the zones were linked, or the database edited by hand).
| Code | Severity | Check |
|------|----------|-------|
| `linked_zone_type` | error | Only primary zones can be linked |
| `linked_zone_name` | error | Linked zones have the same name |
| `linked_mixed` | error | A name and type in a zone is either shared or local, not both |
| `linked_out_of_sync` | error | Every view that doesn't override a shared name and type has the same records for it. Link the zones again (`jarl zone link`) to work out what is shared |
| `linked_zone_alone` | info | A zone linked with no other zone |
## Blocking
From [blocking.md](blocking.md).
docs/views.md
+81 -9
View File
@@ -88,19 +88,27 @@ and [exposure.md](exposure.md) to set up response rate limiting.
### 4. Give the external view its zones
**Different data per view (split DNS).** Copy the zone, then change what
should differ:
**Mostly the same, a few differences (split DNS).** Create the external
copy *linked* ([below](#linked-zones)): Jarl keeps the shared records the
same in both views, and each view can have records of its own:
```sh
jarl zone create adbraun.lol --view external --link-with internal
jarl record set adbraun.lol www A 203.0.113.20 --view external --local # public address, external only
jarl record delete adbraun.lol nas-internal A --view external # gone from both: it was shared
```
Delete records you don't want outside before you link, or make them local
to the internal view first (`jarl record update ID --local`): a shared
record is in both views.
**Two separate copies.** `--clone-from` copies the zone once; from then on
the two are separate zones, and a record added to one isn't in the other:
```sh
jarl zone create adbraun.lol --view external --clone-from adbraun.lol --clone-view internal
jarl record list adbraun.lol --view external
jarl record update <id> --data 203.0.113.20 # public address instead of 10.10.0.20
jarl record delete adbraun.lol nas-internal A --view external
```
From then on the two copies are separate zones. A record added to one isn't
in the other, and the serials are separate.
**The same data in both views.** Use an `in-view` zone. The external view
then serves the internal view's zone, so there is one copy to maintain:
@@ -160,6 +168,67 @@ shows one (it needs `tsig:write` and is audited). Key names starting with
`jarl-view-` are reserved, and the view keys can be used in your own
options (`allow-transfer { key jarl-view-external; }`).
## Linked zones
Most split-horizon zones are the same in every view apart from a few
names. Linking zones of the same name in different views lets Jarl keep
the shared records in step, while each view can still have records of its
own and its own zone options.
* **Shared records** are in every linked view. Adding, changing,
disabling or deleting one in any view does the same in the others, in
the same changeset: the diff shows every view, and history, undo and
`jarl check` treat them together.
* **Local records** are in one view only (`--local`, or **Only here** in
the web UI). A local record overrides the shared records of the same name
and type in that view: `www A 10.0.10.5` local to internal, while the
external view keeps the shared `www A 203.0.113.20`. Delete the local
records and the view gets the shared ones back.
* A new record joins the set of the same name and type: local if that set
is local in its view, shared otherwise.
* **Sharing a version** (`jarl record update ID --shared`, **Share** in the
web UI) makes that view's records of that name and type the shared
version: the other views' records of that name and type are replaced.
* Zones stay separate in named, so each keeps its own serial, options
(allow-transfer, DNSSEC signing, ...) and file, and the views keep their
own `match-clients`, recursion and order.
```sh
jarl zone link adbraun.lol --view internal --with external # link two existing zones
jarl zone create adbraun.lol --view vps --link-with external # a new zone, linked from the start
jarl record list adbraun.lol --view internal # LINK column: shared or local
jarl record add adbraun.lol nas A 10.0.10.20 --view internal --local
jarl record update 1234 --local # this name and type: only this view
jarl record update 1234 --shared # this view's version, everywhere
jarl zone unlink adbraun.lol --view vps # records stay, all local
```
**Linking never changes what named answers.** A name and type with the
same records in every view becomes shared; one that differs stays local to
each view (Jarl lists them). Share the right version afterwards. Unlinking
keeps every record, all local; a link left with one zone is dissolved, as
when the other zone is deleted.
**Permissions** are checked in every view a change reaches. A token with
a grant for one view only (`views=internal`) can change that view's local
records and make overrides, but not a shared record, since that would
change the other views too: Jarl says so and suggests a local record. A
grant without a view (the usual `zones=adbraun.lol`) covers every view.
**Importing a zone file** into a linked zone (`jarl zone import`) adds
the records like any others: shared, unless the name and type is local
there. With `--replace`, shared records missing from the file are deleted
in every linked view.
**ACME challenges** are written once per link, and so reach every linked
view; `jarl acme`, lego's httpreq and certificates Jarl obtains all do
this.
**Compared with BIND's `in-view`**, where one view serves another's zone
as it is: linked zones can differ per view, keep their own options, and
don't depend on the view order (`in-view` can only use a view defined
before it).
## Living with views
* Commands that name a zone that exists in several views need `--view`
@@ -167,7 +236,10 @@ options (`allow-transfer { key jarl-view-external; }`).
guess.
* `jarl acme` writes challenge records into **every** view that has the
zone, so Let's Encrypt (external) and internal clients see the same
thing. Use `--view` to limit it.
thing (once per link, for linked zones). Use `--view` to limit it.
* `--view all` (or a list) on record commands changes each linked zone
once: the change reaches the others through the link. With `--local` it
goes to each view named.
* `jarl view order internal external` changes the match order, and
`jarl view list` shows it.
* Deleting a view is refused while it still has zones, unless you pass