diff options
Diffstat (limited to 'doc/arm/catz.inc.rst')
| -rw-r--r-- | doc/arm/catz.inc.rst | 301 |
1 files changed, 301 insertions, 0 deletions
diff --git a/doc/arm/catz.inc.rst b/doc/arm/catz.inc.rst new file mode 100644 index 0000000..fec0759 --- /dev/null +++ b/doc/arm/catz.inc.rst @@ -0,0 +1,301 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +.. _catz-info: + +Catalog Zones +------------- + +A "catalog zone" is a special DNS zone that contains a list of other +zones to be served, along with their configuration parameters. Zones +listed in a catalog zone are called "member zones." When a catalog zone +is loaded or transferred to a secondary server which supports this +functionality, the secondary server creates the member zones +automatically. When the catalog zone is updated (for example, to add or +delete member zones, or change their configuration parameters), those +changes are immediately put into effect. Because the catalog zone is a +normal DNS zone, these configuration changes can be propagated using the +standard AXFR/IXFR zone transfer mechanism. + +Catalog zones' format and behavior are specified as an Internet draft +for interoperability among DNS implementations. The +latest revision of the DNS catalog zones draft can be found here: +https://datatracker.ietf.org/doc/draft-toorop-dnsop-dns-catalog-zones/ . + +Principle of Operation +~~~~~~~~~~~~~~~~~~~~~~ + +Normally, if a zone is to be served by a secondary server, the +:iscman:`named.conf` file on the server must list the zone, or the zone must +be added using :option:`rndc addzone`. In environments with a large number of +secondary servers, and/or where the zones being served are changing +frequently, the overhead involved in maintaining consistent zone +configuration on all the secondary servers can be significant. + +A catalog zone is a way to ease this administrative burden: it is a DNS +zone that lists member zones that should be served by secondary servers. +When a secondary server receives an update to the catalog zone, it adds, +removes, or reconfigures member zones based on the data received. + +To use a catalog zone, it must first be set up as a normal zone on both the +primary and secondary servers that are configured to use it. It +must also be added to a :any:`catalog-zones` list in the :namedconf:ref:`options` or +:any:`view` statement in :iscman:`named.conf`. This is comparable to the way a +policy zone is configured as a normal zone and also listed in a +:any:`response-policy` statement. + +To use the catalog zone feature to serve a new member zone: + +- Set up the member zone to be served on the primary as normal. This + can be done by editing :iscman:`named.conf` or by running + :option:`rndc addzone`. + +- Add an entry to the catalog zone for the new member zone. This can + be done by editing the catalog zone's zone file and running + :option:`rndc reload`, or by updating the zone using :iscman:`nsupdate`. + +The change to the catalog zone is propagated from the primary to all +secondaries using the normal AXFR/IXFR mechanism. When the secondary receives the +update to the catalog zone, it detects the entry for the new member +zone, creates an instance of that zone on the secondary server, and points +that instance to the :any:`primaries` specified in the catalog zone data. The +newly created member zone is a normal secondary zone, so BIND +immediately initiates a transfer of zone contents from the primary. Once +complete, the secondary starts serving the member zone. + +Removing a member zone from a secondary server requires only +deleting the member zone's entry in the catalog zone; the change to the +catalog zone is propagated to the secondary server using the normal +AXFR/IXFR transfer mechanism. The secondary server, on processing the +update, notices that the member zone has been removed, stops +serving the zone, and removes it from its list of configured zones. +However, removing the member zone from the primary server must be done +by editing the configuration file or running +:option:`rndc delzone`. + +Configuring Catalog Zones +~~~~~~~~~~~~~~~~~~~~~~~~~ +.. namedconf:statement:: catalog-zones + :tags: zone + :short: Configures catalog zones in :iscman:`named.conf`. + +Catalog zones are configured with a :any:`catalog-zones` statement in the +:namedconf:ref:`options` or :any:`view` section of :iscman:`named.conf`. For example: + +:: + + catalog-zones { + zone "catalog.example" + default-primaries { 10.53.0.1; } + in-memory no + zone-directory "catzones" + min-update-interval 10; + }; + +This statement specifies that the zone ``catalog.example`` is a catalog +zone. This zone must be properly configured in the same view. In most +configurations, it would be a secondary zone. + +The options following the zone name are not required, and may be +specified in any order. + +``default-masters`` + Synonym for ``default-primaries``. + +``default-primaries`` + This option defines the default primaries for member + zones listed in a catalog zone, and can be overridden by options within + a catalog zone. If no such options are included, then member zones + transfer their contents from the servers listed in this option. + +``in-memory`` + This option, if set to ``yes``, causes member zones to be + stored only in memory. This is functionally equivalent to configuring a + secondary zone without a :any:`file` option. The default is ``no``; member + zones' content is stored locally in a file whose name is + automatically generated from the view name, catalog zone name, and + member zone name. + +``zone-directory`` + This option causes local copies of member zones' zone files to be + stored in the specified directory, if ``in-memory`` is not set to + ``yes``. The default is to store zone files in the server's working + directory. A non-absolute pathname in ``zone-directory`` is assumed + to be relative to the working directory. + +``min-update-interval`` + This option sets the minimum interval between updates to catalog + zones, in seconds. If an update to a catalog zone (for example, via + IXFR) happens less than ``min-update-interval`` seconds after the + most recent update, the changes are not carried out until this + interval has elapsed. The default is 5 seconds. + +Catalog zones are defined on a per-view basis. Configuring a non-empty +:any:`catalog-zones` statement in a view automatically turns on +:any:`allow-new-zones` for that view. This means that :option:`rndc addzone` +and :option:`rndc delzone` also work in any view that supports catalog +zones. + +Catalog Zone Format +~~~~~~~~~~~~~~~~~~~ + +A catalog zone is a regular DNS zone; therefore, it must have a single +``SOA`` and at least one ``NS`` record. + +A record stating the version of the catalog zone format is also +required. If the version number listed is not supported by the server, +then a catalog zone may not be used by that server. + +:: + + catalog.example. IN SOA . . 2016022901 900 600 86400 1 + catalog.example. IN NS invalid. + version.catalog.example. IN TXT "2" + +Note that this record must have the domain name +``version.catalog-zone-name``. The data +stored in a catalog zone is indicated by the domain name label +immediately before the catalog zone domain. Currently BIND supports catalog zone +schema versions "1" and "2". + +Also note that the catalog zone must have an NS record in order to be a valid +DNS zone, and using the value "invalid." for NS is recommended. + +A member zone is added by including a ``PTR`` resource record in the +``zones`` sub-domain of the catalog zone. The record label can be any unique label. +The target of the PTR record is the member zone name. For example, to add member zones +``domain.example`` and ``domain2.example``: + +:: + + 5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN PTR domain.example. + uniquelabel.zones.catalog.example. IN PTR domain2.example. + +The label is necessary to identify custom properties (see below) for a specific member zone. +Also, the zone state can be reset by changing its label, in which case BIND will remove +the member zone and add it back. + +Catalog Zone Custom Properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +BIND uses catalog zones custom properties to define different properties which +can be set either globally for the whole catalog +zone or for a single member zone. Global custom properties override the settings +in the configuration file, and member zone custom properties override global +custom properties. + +For the version "1" of the schema custom properties must be placed without a special suffix. + +For the version "2" of the schema custom properties must be placed under the ".ext" suffix. + +Global custom properties are set at the apex of the catalog zone, e.g.: + +:: + + primaries.ext.catalog.example. IN AAAA 2001:db8::1 + +BIND currently supports the following custom properties: + +- A simple :any:`primaries` definition: + + :: + + primaries.ext.catalog.example. IN A 192.0.2.1 + + + This custom property defines a primary server for the member zones, which can be + either an A or AAAA record. If multiple primaries are set, the order in + which they are used is random. + + Note: ``masters`` can be used as a synonym for :any:`primaries`. + +- A :any:`primaries` with a TSIG key defined: + + :: + + label.primaries.ext.catalog.example. IN A 192.0.2.2 + label.primaries.ext.catalog.example. IN TXT "tsig_key_name" + + + This custom property defines a primary server for the member zone with a TSIG + key set. The TSIG key must be configured in the configuration file. + ``label`` can be any valid DNS label. + + Note: ``masters`` can be used as a synonym for :any:`primaries`. + +- :any:`allow-query` and :any:`allow-transfer` ACLs: + + :: + + allow-query.ext.catalog.example. IN APL 1:10.0.0.1/24 + allow-transfer.ext.catalog.example. IN APL !1:10.0.0.1/32 1:10.0.0.0/24 + + + These custom properties are the equivalents of :any:`allow-query` and + :any:`allow-transfer` options in a zone declaration in the :iscman:`named.conf` + configuration file. The ACL is processed in order; if there is no + match to any rule, the default policy is to deny access. For the + syntax of the APL RR, see :rfc:`3123`. + +The member zone-specific custom properties are defined the same way as global +custom properties, but in the member zone subdomain: + +:: + + primaries.ext.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN A 192.0.2.2 + label.primaries.ext.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN AAAA 2001:db8::2 + label.primaries.ext.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN TXT "tsig_key_name" + allow-query.ext.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN APL 1:10.0.0.0/24 + primaries.ext.uniquelabel.zones.catalog.example. IN A 192.0.2.3 + +Custom properties defined for a specific zone override the +global custom properties defined in the catalog zone. These in turn override the +global options defined in the :any:`catalog-zones` statement in the +configuration file. + +Note that none of the global records for a custom property are inherited if any +records are defined for that custom property for the specific zone. For example, +if the zone had a :any:`primaries` record of type A but not AAAA, it +would *not* inherit the type AAAA record from the global custom property +or from the global option in the configuration file. + +Change of Ownership (coo) +~~~~~~~~~~~~~~~~~~~~~~~~~ + +BIND supports the catalog zones "Change of Ownership" (coo) property. When the +same entry which exists in one catalog zone is added into another catalog zone, +the default behavior for BIND is to ignore it, and continue serving the zone +using the catalog zone where it was originally existed, unless it is removed +from there, then it can be added into the new one. + +Using the ``coo`` property it is possible to gracefully move a zone from one +catalog zone into another, by letting the catalog consumers know that it is +permitted to do so. To do that, the original catalog zone should be updated with +a new record with ``coo`` custom property: + +:: + + uniquelabel.zones.catalog.example. IN PTR domain2.example. + coo.uniquelabel.zones.catalog.example. IN PTR catalog2.example. + +Here, the ``catalog.example`` catalog zone gives permission for the member zone +with label "uniquelabel" to be transferred into ``catalog2.example`` catalog +zone. Catalog consumers which support the ``coo`` property will then take note, +and when the zone is finally added into ``catalog2.example`` catalog zone, +catalog consumers will change the ownership of the zone from ``catalog.example`` +to ``catalog2.example``. BIND's implementation simply deletes the zone from the +old catalog zone and adds it back into the new catalog zone, which also means +that all associated state for the just migrated zone will be reset, including +when the unique label is the same. + +The record with ``coo`` custom property can be later deleted by the +catalog zone operator after confirming that all the consumers have received +it and have successfully changed the ownership of the zone. |