1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
2..
3.. SPDX-License-Identifier: MPL-2.0
4..
5.. This Source Code Form is subject to the terms of the Mozilla Public
6.. License, v. 2.0.  If a copy of the MPL was not distributed with this
7.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
8..
9.. See the COPYRIGHT file distributed with this work for additional
10.. information regarding copyright ownership.
11
12.. _catz-info:
13
14Catalog Zones
15-------------
16
17A "catalog zone" is a special DNS zone that contains a list of other
18zones to be served, along with their configuration parameters. Zones
19listed in a catalog zone are called "member zones." When a catalog zone
20is loaded or transferred to a secondary server which supports this
21functionality, the secondary server creates the member zones
22automatically. When the catalog zone is updated (for example, to add or
23delete member zones, or change their configuration parameters), those
24changes are immediately put into effect. Because the catalog zone is a
25normal DNS zone, these configuration changes can be propagated using the
26standard AXFR/IXFR zone transfer mechanism.
27
28Catalog zones' format and behavior are specified as an Internet draft
29for interoperability among DNS implementations. The
30latest revision of the DNS catalog zones draft can be found here:
31https://datatracker.ietf.org/doc/draft-toorop-dnsop-dns-catalog-zones/ .
32
33Principle of Operation
34~~~~~~~~~~~~~~~~~~~~~~
35
36Normally, if a zone is to be served by a secondary server, the
37:iscman:`named.conf` file on the server must list the zone, or the zone must
38be added using :option:`rndc addzone`. In environments with a large number of
39secondary servers, and/or where the zones being served are changing
40frequently, the overhead involved in maintaining consistent zone
41configuration on all the secondary servers can be significant.
42
43A catalog zone is a way to ease this administrative burden: it is a DNS
44zone that lists member zones that should be served by secondary servers.
45When a secondary server receives an update to the catalog zone, it adds,
46removes, or reconfigures member zones based on the data received.
47
48To use a catalog zone, it must first be set up as a normal zone on both the
49primary and secondary servers that are configured to use it. It
50must also be added to a :any:`catalog-zones` list in the :namedconf:ref:`options` or
51:any:`view` statement in :iscman:`named.conf`. This is comparable to the way a
52policy zone is configured as a normal zone and also listed in a
53:any:`response-policy` statement.
54
55To use the catalog zone feature to serve a new member zone:
56
57-  Set up the member zone to be served on the primary as normal. This
58   can be done by editing :iscman:`named.conf` or by running
59   :option:`rndc addzone`.
60
61-  Add an entry to the catalog zone for the new member zone. This can
62   be done by editing the catalog zone's zone file and running
63   :option:`rndc reload`, or by updating the zone using :iscman:`nsupdate`.
64
65The change to the catalog zone is propagated from the primary to all
66secondaries using the normal AXFR/IXFR mechanism. When the secondary receives the
67update to the catalog zone, it detects the entry for the new member
68zone, creates an instance of that zone on the secondary server, and points
69that instance to the :any:`primaries` specified in the catalog zone data. The
70newly created member zone is a normal secondary zone, so BIND
71immediately initiates a transfer of zone contents from the primary. Once
72complete, the secondary starts serving the member zone.
73
74Removing a member zone from a secondary server requires only
75deleting the member zone's entry in the catalog zone; the change to the
76catalog zone is propagated to the secondary server using the normal
77AXFR/IXFR transfer mechanism. The secondary server, on processing the
78update, notices that the member zone has been removed, stops
79serving the zone, and removes it from its list of configured zones.
80However, removing the member zone from the primary server must be done
81by editing the configuration file or running
82:option:`rndc delzone`.
83
84Configuring Catalog Zones
85~~~~~~~~~~~~~~~~~~~~~~~~~
86.. namedconf:statement:: catalog-zones
87   :tags: zone
88   :short: Configures catalog zones in :iscman:`named.conf`.
89
90Catalog zones are configured with a :any:`catalog-zones` statement in the
91:namedconf:ref:`options` or :any:`view` section of :iscman:`named.conf`. For example:
92
93::
94
95   catalog-zones {
96       zone "catalog.example"
97            default-primaries { 10.53.0.1; }
98            in-memory no
99            zone-directory "catzones"
100            min-update-interval 10;
101   };
102
103This statement specifies that the zone ``catalog.example`` is a catalog
104zone. This zone must be properly configured in the same view. In most
105configurations, it would be a secondary zone.
106
107The options following the zone name are not required, and may be
108specified in any order.
109
110``default-masters``
111   Synonym for ``default-primaries``.
112
113``default-primaries``
114   This option defines the default primaries for member
115   zones listed in a catalog zone, and can be overridden by options within
116   a catalog zone. If no such options are included, then member zones
117   transfer their contents from the servers listed in this option.
118
119``in-memory``
120   This option, if set to ``yes``, causes member zones to be
121   stored only in memory. This is functionally equivalent to configuring a
122   secondary zone without a :any:`file` option. The default is ``no``; member
123   zones' content is stored locally in a file whose name is
124   automatically generated from the view name, catalog zone name, and
125   member zone name.
126
127``zone-directory``
128   This option causes local copies of member zones' zone files to be
129   stored in the specified directory, if ``in-memory`` is not set to
130   ``yes``. The default is to store zone files in the server's working
131   directory. A non-absolute pathname in ``zone-directory`` is assumed
132   to be relative to the working directory.
133
134``min-update-interval``
135   This option sets the minimum interval between updates to catalog
136   zones, in seconds. If an update to a catalog zone (for example, via
137   IXFR) happens less than ``min-update-interval`` seconds after the
138   most recent update, the changes are not carried out until this
139   interval has elapsed. The default is 5 seconds.
140
141Catalog zones are defined on a per-view basis. Configuring a non-empty
142:any:`catalog-zones` statement in a view automatically turns on
143:any:`allow-new-zones` for that view. This means that :option:`rndc addzone`
144and :option:`rndc delzone` also work in any view that supports catalog
145zones.
146
147Catalog Zone Format
148~~~~~~~~~~~~~~~~~~~
149
150A catalog zone is a regular DNS zone; therefore, it must have a single
151``SOA`` and at least one ``NS`` record.
152
153A record stating the version of the catalog zone format is also
154required. If the version number listed is not supported by the server,
155then a catalog zone may not be used by that server.
156
157::
158
159   catalog.example.    IN SOA . . 2016022901 900 600 86400 1
160   catalog.example.    IN NS invalid.
161   version.catalog.example.    IN TXT "2"
162
163Note that this record must have the domain name
164``version.catalog-zone-name``. The data
165stored in a catalog zone is indicated by the domain name label
166immediately before the catalog zone domain. Currently BIND supports catalog zone
167schema versions "1" and "2".
168
169Also note that the catalog zone must have an NS record in order to be a valid
170DNS zone, and using the value "invalid." for NS is recommended.
171
172A member zone is added by including a ``PTR`` resource record in the
173``zones`` sub-domain of the catalog zone. The record label can be any unique label.
174The target of the PTR record is the member zone name. For example, to add member zones
175``domain.example`` and ``domain2.example``:
176
177::
178
179   5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN PTR domain.example.
180   uniquelabel.zones.catalog.example. IN PTR domain2.example.
181
182The label is necessary to identify custom properties (see below) for a specific member zone.
183Also, the zone state can be reset by changing its label, in which case BIND will remove
184the member zone and add it back.
185
186Catalog Zone Custom Properties
187~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188
189BIND uses catalog zones custom properties to define different properties which
190can be set either globally for the whole catalog
191zone or for a single member zone. Global custom properties override the settings
192in the configuration file, and member zone custom properties override global
193custom properties.
194
195For the version "1" of the schema custom properties must be placed without a special suffix.
196
197For the version "2" of the schema custom properties must be placed under the ".ext" suffix.
198
199Global custom properties are set at the apex of the catalog zone, e.g.:
200
201::
202
203    primaries.ext.catalog.example.    IN AAAA 2001:db8::1
204
205BIND currently supports the following custom properties:
206
207-  A simple :any:`primaries` definition:
208
209   ::
210
211           primaries.ext.catalog.example.    IN A 192.0.2.1
212
213
214   This custom property defines a primary server for the member zones, which can be
215   either an A or AAAA record. If multiple primaries are set, the order in
216   which they are used is random.
217
218   Note: ``masters`` can be used as a synonym for :any:`primaries`.
219
220-  A :any:`primaries` with a TSIG key defined:
221
222   ::
223
224               label.primaries.ext.catalog.example.     IN A 192.0.2.2
225               label.primaries.ext.catalog.example.     IN TXT "tsig_key_name"
226
227
228   This custom property defines a primary server for the member zone with a TSIG
229   key set. The TSIG key must be configured in the configuration file.
230   ``label`` can be any valid DNS label.
231
232   Note: ``masters`` can be used as a synonym for :any:`primaries`.
233
234-  :any:`allow-query` and :any:`allow-transfer` ACLs:
235
236   ::
237
238               allow-query.ext.catalog.example.   IN APL 1:10.0.0.1/24
239               allow-transfer.ext.catalog.example.    IN APL !1:10.0.0.1/32 1:10.0.0.0/24
240
241
242   These custom properties are the equivalents of :any:`allow-query` and
243   :any:`allow-transfer` options in a zone declaration in the :iscman:`named.conf`
244   configuration file. The ACL is processed in order; if there is no
245   match to any rule, the default policy is to deny access. For the
246   syntax of the APL RR, see :rfc:`3123`.
247
248The member zone-specific custom properties are defined the same way as global
249custom properties, but in the member zone subdomain:
250
251::
252
253   primaries.ext.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN A 192.0.2.2
254   label.primaries.ext.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN AAAA 2001:db8::2
255   label.primaries.ext.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN TXT "tsig_key_name"
256   allow-query.ext.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN APL 1:10.0.0.0/24
257   primaries.ext.uniquelabel.zones.catalog.example. IN A 192.0.2.3
258
259Custom properties defined for a specific zone override the
260global custom properties defined in the catalog zone. These in turn override the
261global options defined in the :any:`catalog-zones` statement in the
262configuration file.
263
264Note that none of the global records for a custom property are inherited if any
265records are defined for that custom property for the specific zone. For example,
266if the zone had a :any:`primaries` record of type A but not AAAA, it
267would *not* inherit the type AAAA record from the global custom property
268or from the global option in the configuration file.
269
270Change of Ownership (coo)
271~~~~~~~~~~~~~~~~~~~~~~~~~
272
273BIND supports the catalog zones "Change of Ownership" (coo) property. When the
274same entry which exists in one catalog zone is added into another catalog zone,
275the default behavior for BIND is to ignore it, and continue serving the zone
276using the catalog zone where it was originally existed, unless it is removed
277from there, then it can be added into the new one.
278
279Using the ``coo`` property it is possible to gracefully move a zone from one
280catalog zone into another, by letting the catalog consumers know that it is
281permitted to do so. To do that, the original catalog zone should be updated with
282a new record with ``coo`` custom property:
283
284::
285
286   uniquelabel.zones.catalog.example. IN PTR domain2.example.
287   coo.uniquelabel.zones.catalog.example. IN PTR catalog2.example.
288
289Here, the ``catalog.example`` catalog zone gives permission for the member zone
290with label "uniquelabel" to be transferred into ``catalog2.example`` catalog
291zone. Catalog consumers which support the ``coo`` property will then take note,
292and when the zone is finally added into ``catalog2.example`` catalog zone,
293catalog consumers will change the ownership of the zone from ``catalog.example``
294to ``catalog2.example``. BIND's implementation simply deletes the zone from the
295old catalog zone and adds it back into the new catalog zone, which also means
296that all associated state for the just migrated zone will be reset, including
297when the unique label is the same.
298
299The record with ``coo`` custom property can be later deleted by the
300catalog zone operator after confirming that all the consumers have received
301it and have successfully changed the ownership of the zone.
302