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``named.conf`` file on the server must list the zone, or the zone must
38be added using ``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 ``catalog-zones`` list in the ``options`` or
51``view`` statement in ``named.conf``. This is comparable to the way a
52policy zone is configured as a normal zone and also listed in a
53``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 ``named.conf`` or by running
59   ``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   ``rndc reload``, or by updating the zone using ``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 ``masters`` 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``rndc delzone``.
83
84Configuring Catalog Zones
85~~~~~~~~~~~~~~~~~~~~~~~~~
86
87Catalog zones are configured with a ``catalog-zones`` statement in the
88``options`` or ``view`` section of ``named.conf``. For example:
89
90::
91
92   catalog-zones {
93       zone "catalog.example"
94            default-masters { 10.53.0.1; }
95            in-memory no
96            zone-directory "catzones"
97            min-update-interval 10;
98   };
99
100This statement specifies that the zone ``catalog.example`` is a catalog
101zone. This zone must be properly configured in the same view. In most
102configurations, it would be a secondary zone.
103
104The options following the zone name are not required, and may be
105specified in any order.
106
107``default-masters``
108   This option defines the default primaries for member
109   zones listed in a catalog zone, and can be overridden by options within
110   a catalog zone. If no such options are included, then member zones
111   transfer their contents from the servers listed in this option.
112
113``in-memory``
114   This option, if set to ``yes``, causes member zones to be
115   stored only in memory. This is functionally equivalent to configuring a
116   secondary zone without a ``file`` option. The default is ``no``; member
117   zones' content is stored locally in a file whose name is
118   automatically generated from the view name, catalog zone name, and
119   member zone name.
120
121``zone-directory``
122   This option causes local copies of member zones' zone files to be
123   stored in the specified directory, if ``in-memory`` is not set to
124   ``yes``. The default is to store zone files in the server's working
125   directory. A non-absolute pathname in ``zone-directory`` is assumed
126   to be relative to the working directory.
127
128``min-update-interval``
129   This option sets the minimum interval between updates to catalog
130   zones, in seconds. If an update to a catalog zone (for example, via
131   IXFR) happens less than ``min-update-interval`` seconds after the
132   most recent update, the changes are not carried out until this
133   interval has elapsed. The default is 5 seconds.
134
135Catalog zones are defined on a per-view basis. Configuring a non-empty
136``catalog-zones`` statement in a view automatically turns on
137``allow-new-zones`` for that view. This means that ``rndc addzone``
138and ``rndc delzone`` also work in any view that supports catalog
139zones.
140
141Catalog Zone Format
142~~~~~~~~~~~~~~~~~~~
143
144A catalog zone is a regular DNS zone; therefore, it must have a single
145``SOA`` and at least one ``NS`` record.
146
147A record stating the version of the catalog zone format is also
148required. If the version number listed is not supported by the server,
149then a catalog zone may not be used by that server.
150
151::
152
153   catalog.example.    IN SOA . . 2016022901 900 600 86400 1
154   catalog.example.    IN NS nsexample.
155   version.catalog.example.    IN TXT "1"
156
157Note that this record must have the domain name
158``version.catalog-zone-name``. The data
159stored in a catalog zone is indicated by the domain name label
160immediately before the catalog zone domain.
161
162Catalog zone options can be set either globally for the whole catalog
163zone or for a single member zone. Global options override the settings
164in the configuration file, and member zone options override global
165options.
166
167Global options are set at the apex of the catalog zone, e.g.:
168
169::
170
171    masters.catalog.example.    IN AAAA 2001:db8::1
172
173BIND currently supports the following options:
174
175-  A simple ``masters`` definition:
176
177   ::
178
179           masters.catalog.example.    IN A 192.0.2.1
180
181
182   This option defines a primary server for the member zones, which can be
183   either an A or AAAA record. If multiple primaries are set, the order in
184   which they are used is random.
185
186-  A ``masters`` with a TSIG key defined:
187
188   ::
189
190               label.masters.catalog.example.     IN A 192.0.2.2
191               label.masters.catalog.example.     IN TXT "tsig_key_name"
192
193
194   This option defines a primary server for the member zone with a TSIG
195   key set. The TSIG key must be configured in the configuration file.
196   ``label`` can be any valid DNS label.
197
198-  ``allow-query`` and ``allow-transfer`` ACLs:
199
200   ::
201
202               allow-query.catalog.example.   IN APL 1:10.0.0.1/24
203               allow-transfer.catalog.example.    IN APL !1:10.0.0.1/32 1:10.0.0.0/24
204
205
206   These options are the equivalents of ``allow-query`` and
207   ``allow-transfer`` in a zone declaration in the ``named.conf``
208   configuration file. The ACL is processed in order; if there is no
209   match to any rule, the default policy is to deny access. For the
210   syntax of the APL RR, see :rfc:`3123`.
211
212A member zone is added by including a ``PTR`` resource record in the
213``zones`` sub-domain of the catalog zone. The record label is a
214``SHA-1`` hash of the member zone name in wire format. The target of the
215PTR record is the member zone name. For example, to add the member zone
216``domain.example``:
217
218::
219
220   5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN PTR domain.example.
221
222The hash is necessary to identify options for a specific member zone.
223The member zone-specific options are defined the same way as global
224options, but in the member zone subdomain:
225
226::
227
228   masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN A 192.0.2.2
229   label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN AAAA 2001:db8::2
230   label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN TXT "tsig_key"
231   allow-query.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN APL 1:10.0.0.0/24
232
233Options defined for a specific zone override the
234global options defined in the catalog zone. These in turn override the
235global options defined in the ``catalog-zones`` statement in the
236configuration file.
237
238Note that none of the global records for an option are inherited if any
239records are defined for that option for the specific zone. For example,
240if the zone had a ``masters`` record of type A but not AAAA, it
241would *not* inherit the type AAAA record from the global option.
242