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