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