Linked zones: shared records kept in step across views

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>

cmd/jarl/acme.go

@@ -83,7 +83,7 @@ func acmeZones(c *client.Client, name, view string) ([]acme.Zone, error) {
 	}
 	refs := make([]acme.Zone, len(zones))
 	for i, z := range zones {
-		refs[i] = acme.Zone{Name: z.Name, View: z.View}
+		refs[i] = acme.Zone{Name: z.Name, View: z.View, Link: z.LinkGroup}
 	}
 	out := acme.Zones(name, refs, view)
 	if len(out) == 0 {

cmd/jarl/multiview.go

@@ -12,34 +12,60 @@ import (
 // zoneViews expands a --view value for a record command: "" or one view
 // as it is, "a,b" to those views, and "all" to every view that has the
 // zone.
+// localFanOut is set by commands making local changes (--local), which
+// go to every view named even when the zones are linked.
+var localFanOut bool
+
 func zoneViews(c *client.Client, zone, view string) ([]string, error) {
 	if view != "all" && !strings.Contains(view, ",") {
 		return []string{view}, nil
 	}
-	if view != "all" {
-		var out []string
-		for _, v := range strings.Split(view, ",") {
-			if v = strings.TrimSpace(v); v != "" {
-				out = append(out, v)
-			}
-		}
-		return out, nil
-	}
 	var zones []api.Zone
 	if err := c.Get(ctx(), "/zones", nil, &zones); err != nil {
 		return nil, err
 	}
 	want := strings.ToLower(strings.TrimSuffix(zone, "."))
+	link := map[string]int64{}
 	var out []string
 	for _, z := range zones {
 		if strings.ToLower(strings.TrimSuffix(z.Display, ".")) == want && z.View != "" {
-			out = append(out, z.View)
+			link[z.View] = z.LinkGroup
+			if view == "all" {
+				out = append(out, z.View)
+			}
+		}
+	}
+	if view != "all" {
+		for _, v := range strings.Split(view, ",") {
+			if v = strings.TrimSpace(v); v != "" {
+				out = append(out, v)
+			}
 		}
 	}
 	if len(out) == 0 {
 		return nil, fmt.Errorf("zone %s is in no view", zone)
 	}
-	return out, nil
+	// Linked zones (docs/views.md#linked-zones) get a shared change once:
+	// Jarl copies it to the others. A local change goes to each.
+	if localFanOut {
+		return out, nil
+	}
+	var dedup []string
+	first := map[int64]string{}
+	for _, v := range out {
+		g := link[v]
+		if g != 0 {
+			if f, ok := first[g]; ok {
+				if !flagQuiet {
+					fmt.Fprintf(os.Stderr, "view %s: linked with %s, so it gets the change from there\n", v, f)
+				}
+				continue
+			}
+			first[g] = v
+		}
+		dedup = append(dedup, v)
+	}
+	return dedup, nil
 }
 
 // perView runs a record command once per view. With several views, the

cmd/jarl/zones.go

@@ -93,6 +93,9 @@ func zoneCmd() *cobra.Command {
 				if z.InView != "" {
 					fmt.Fprintf(w, "In view:\t%s\n", z.InView)
 				}
+				if len(z.LinkedWith) > 0 {
+					fmt.Fprintf(w, "Linked with:\t%s (shared records are kept in step; 'jarl record list' shows which are local)\n", strings.Join(z.LinkedWith, ", "))
+				}
 				if z.ZoneFile != "" {
 					fmt.Fprintf(w, "File:\t%s\n", z.ZoneFile)
 				}
@@ -105,7 +108,7 @@ func zoneCmd() *cobra.Command {
 	show.Flags().StringVar(&view, "view", "", "view of the zone (when the name exists in several views)")
 
 	var ns, records, primaries, forwarders, opts []string
-	var contact, comment, cloneFrom, file, inView, forward string
+	var contact, comment, cloneFrom, file, inView, forward, linkWith string
 	var ttl uint32
 	create := &cobra.Command{
 		Use:   "create NAME",
@@ -120,7 +123,8 @@ and a network between octet boundaries, like a /22, gets one zone per /24
   jarl zone create 10.0.8.0/22            # 8-11.0.10.in-addr.arpa
   jarl zone create partner.example --type secondary --primary 192.0.2.53
   jarl zone create consul --type forward --forwarder "127.0.0.1 port 8600"
-  jarl zone create example.com --view external --clone-from example.com --clone-view internal`,
+  jarl zone create example.com --view external --clone-from example.com --clone-view internal
+  jarl zone create example.com --view vps --link-with external   # linked: shared records kept in step`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			c, err := newClient()
@@ -149,6 +153,9 @@ and a network between octet boundaries, like a /22, gets one zone per /24
 			if inView != "" {
 				body["in_view"] = inView
 			}
+			if linkWith != "" {
+				body["link_with"] = linkWith
+			}
 			var recs []map[string]any
 			for _, r := range records {
 				f := strings.Fields(r)
@@ -219,6 +226,7 @@ and a network between octet boundaries, like a /22, gets one zone per /24
 	create.Flags().StringVar(&cloneView, "clone-view", "", "view of --clone-from")
 	create.Flags().StringVar(&file, "file", "", "zone file (hint and redirect zones)")
 	create.Flags().StringVar(&inView, "in-view", "", "for in-view zones: the view to share the zone from")
+	create.Flags().StringVar(&linkWith, "link-with", "", "link with the zone of the same name in this view: copy its shared records and keep them in step (docs/views.md#linked-zones)")
 	create.Flags().StringVar(&comment, "comment", "", "comment")
 
 	var refresh, retry, expire, minimum, serial uint32
@@ -416,7 +424,7 @@ equal to the file: records not in the file are deleted.`,
 	importCmd.Flags().BoolVar(&replace, "replace", false, "delete records that are not in the file")
 	importCmd.Flags().BoolVar(&useSOA, "use-soa", false, "also take SOA timers and $TTL from the file")
 
-	cmd.AddCommand(list, show, create, update, del, toggle(true), toggle(false), fileCmd, importCmd, zoneSerialsCmd(), zoneDelegationCmd(), zoneDNSSECCmd(), zoneRegistrarCmd())
+	cmd.AddCommand(list, show, create, update, del, toggle(true), toggle(false), fileCmd, importCmd, zoneSerialsCmd(), zoneDelegationCmd(), zoneDNSSECCmd(), zoneRegistrarCmd(), zoneLinkCmd(true), zoneLinkCmd(false))
 	return cmd
 }
 
@@ -456,8 +464,25 @@ const viewsFlagHelp = "view of the zone; several (internal,external) or \"all\"
 func recordCmd() *cobra.Command {
 	cmd := &cobra.Command{Use: "record", Aliases: []string{"records", "rr"}, Short: "Manage records in primary zones"}
 	var view, name, typ, search, comment, ttlArg string
-	var ptr, missingOK, yes, onlyDisabled, wide bool
+	var ptr, missingOK, yes, onlyDisabled, wide, local, shared bool
 	var id int64
+	// linkFlags adds --local and --shared (linked zones) to a command.
+	linkFlags := func(c *cobra.Command, what string) {
+		c.Flags().BoolVar(&local, "local", false, "linked zones: "+what+" in this view only (overriding the shared records of this name and type here)")
+		c.Flags().BoolVar(&shared, "shared", false, "linked zones: "+what+" in every linked view (this version becomes every view's)")
+	}
+	linkBody := func(body map[string]any) error {
+		switch {
+		case local && shared:
+			return fmt.Errorf("give --local or --shared, not both")
+		case local:
+			body["local"] = true
+			localFanOut = true
+		case shared:
+			body["local"] = false
+		}
+		return nil
+	}
 
 	list := &cobra.Command{
 		Use:   "list ZONE",
@@ -479,8 +504,15 @@ func recordCmd() *cobra.Command {
 			if err := c.Get(ctx(), path+"/records", qv, &recs); err != nil {
 				return err
 			}
+			linked := false
+			for _, r := range recs {
+				linked = linked || r.Linked != ""
+			}
 			return output(recs, func(w io.Writer) {
 				rows := [][]string{{"ID", "NAME", "TTL", "TYPE", "DATA", "COMMENT"}}
+				if linked {
+					rows[0] = []string{"ID", "NAME", "TTL", "TYPE", "LINK", "DATA", "COMMENT"}
+				}
 				for _, r := range recs {
 					ttl := fmt.Sprint(r.EffectiveTTL)
 					if r.TTL == nil {
@@ -490,10 +522,18 @@ func recordCmd() *cobra.Command {
 					if r.Disabled {
 						comment = strings.TrimSpace("[disabled] " + comment)
 					}
+					if linked {
+						rows = append(rows, []string{fmt.Sprint(r.ID), r.RelativeName, ttl, r.Type, r.Linked, r.Data, comment})
+						continue
+					}
 					rows = append(rows, []string{fmt.Sprint(r.ID), r.RelativeName, ttl, r.Type, r.Data, comment})
 				}
 				if !wide {
-					fitColumn(rows, 4)
+					col := 4
+					if linked {
+						col = 5
+					}
+					fitColumn(rows, col)
 				}
 				for _, row := range rows {
 					fmt.Fprintln(w, strings.Join(row, "\t"))
@@ -535,6 +575,9 @@ and splitting are automatic).
 			if ptr {
 				body["ptr"] = true
 			}
+			if err := linkBody(body); err != nil {
+				return err
+			}
 			views, err := zoneViews(c, args[0], view)
 			if err != nil {
 				return err
@@ -549,6 +592,7 @@ and splitting are automatic).
 	add.Flags().StringVar(&ttlArg, "ttl", "", "TTL in seconds (default: the RRset's or the zone's)")
 	add.Flags().StringVar(&comment, "comment", "", "comment")
 	add.Flags().BoolVar(&ptr, "ptr", false, "also add the PTR record (A/AAAA)")
+	linkFlags(add, "add it")
 
 	var data string
 	update := &cobra.Command{
@@ -582,6 +626,9 @@ and splitting are automatic).
 			if ptr {
 				body["ptr"] = true
 			}
+			if err := linkBody(body); err != nil {
+				return err
+			}
 			if len(body) == 0 {
 				return fmt.Errorf("nothing to change (see --help)")
 			}
@@ -598,6 +645,8 @@ and splitting are automatic).
 	update.Flags().StringVar(&ttlArg, "ttl", "", `new TTL, or "default" for the zone default`)
 	update.Flags().StringVar(&comment, "comment", "", "new comment")
 	update.Flags().BoolVar(&ptr, "ptr", false, "move the PTR record along (A/AAAA)")
+	update.Flags().BoolVar(&local, "local", false, "linked zones: make this name and type local to the record's view (an override)")
+	update.Flags().BoolVar(&shared, "shared", false, "linked zones: share this name and type with the linked views; this view's version becomes every view's")
 
 	del := &cobra.Command{
 		Use:   "delete ZONE NAME TYPE [DATA...]  |  delete --id ID",
@@ -678,6 +727,9 @@ spaces.
 			if comment != "" {
 				body["comment"] = comment
 			}
+			if err := linkBody(body); err != nil {
+				return err
+			}
 			views, err := zoneViews(c, args[0], view)
 			if err != nil {
 				return err
@@ -691,6 +743,7 @@ spaces.
 	set.Flags().StringVar(&view, "view", "", viewsFlagHelp)
 	set.Flags().StringVar(&ttlArg, "ttl", "", "TTL for the RRset")
 	set.Flags().StringVar(&comment, "comment", "", "comment for new records")
+	linkFlags(set, "set it")
 
 	toggle := func(disable bool) *cobra.Command {
 		verb := "enable"
@@ -829,3 +882,58 @@ func fitColumn(rows [][]string, col int) {
 		}
 	}
 }
+
+// zoneLinkCmd is 'zone link' and 'zone unlink' (docs/views.md#linked-zones).
+func zoneLinkCmd(link bool) *cobra.Command {
+	var view string
+	var with []string
+	cmd := &cobra.Command{
+		Use:   "link ZONE --view VIEW [--with VIEW...]",
+		Short: "Link zones of the same name in several views: shared records are kept in step",
+		Long: `Links a zone with the zones of the same name in other views (--with, or
+every view that has one). Jarl then keeps their shared records in step: a
+change to one reaches the others in the same changeset. Each view can
+still have records of its own (record add/set --local), which override
+the shared records of that name and type there, and every zone keeps its
+own options, so views can still differ in who they answer and how.
+
+Linking never changes what named answers: a name and type with the same
+records in every view becomes shared, and one that differs stays local to
+each view. Share one later from the view whose version is right:
+jarl record update ID --shared.`,
+		Example: `  jarl zone link adbraun.lol --view external --with vps
+  jarl zone create adbraun.lol --view vps --link-with external   # a new zone, linked from the start
+  jarl zone unlink adbraun.lol --view vps`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := newClient()
+			if err != nil {
+				return err
+			}
+			path, qv := zonePath(args[0], view)
+			verb := "unlink"
+			var body any
+			if link {
+				verb = "link"
+				body = map[string]any{"with": with}
+			}
+			resp, err := c.Mutate(ctx(), "POST", path+"/"+verb, qv, body)
+			if err != nil {
+				return err
+			}
+			return report(resp)
+		},
+	}
+	cmd.Flags().StringVar(&view, "view", "", "view of the zone")
+	if link {
+		cmd.Flags().StringSliceVar(&with, "with", nil, "views to link with (default: every view with a zone of that name)")
+		return cmd
+	}
+	cmd.Use = "unlink ZONE --view VIEW"
+	cmd.Short = "Take a zone out of its link: its records stay, all local"
+	cmd.Long = `Takes a zone out of its link. Its records stay as they are, all local to
+its view, and the other zones of the link keep theirs. A link left with one
+zone is dissolved.`
+	cmd.Example = "  jarl zone unlink adbraun.lol --view vps"
+	return cmd
+}