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