diff --git a/doc/arm/catz.rst b/doc/arm/catz.rst index 517d490ea1..a41bf78f09 100644 --- a/doc/arm/catz.rst +++ b/doc/arm/catz.rst @@ -25,76 +25,76 @@ 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 slave server which supports this -functionality, the slave server will create the member 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 +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. As of this release, the +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-muks-dnsop-dns-catalog-zones/ +https://datatracker.ietf.org/doc/draft-toorop-dnsop-dns-catalog-zones/. Principle of Operation ~~~~~~~~~~~~~~~~~~~~~~ -Normally, if a zone is to be served by a slave server, the +Normally, if a zone is to be served by a secondary server, the ``named.conf`` file on the server must list the zone, or the zone must be added using ``rndc addzone``. In environments with a large number of -slave servers and/or where the zones being served are changing +secondary servers, and/or where the zones being served are changing frequently, the overhead involved in maintaining consistent zone -configuration on all the slave servers can be significant. +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 slave servers. -When a slave server receives an update to the catalog zone, it adds, +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 the -master and the on slave servers that will be configured to use it. It +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 ``catalog-zones`` list in the ``options`` or -``view`` statement in ``named.conf``. (This is comparable to the way a +``view`` statement in ``named.conf``. This is comparable to the way a policy zone is configured as a normal zone and also listed in a -``response-policy`` statement.) +``response-policy`` statement. To use the catalog zone feature to serve a new member zone: -- Set up the the member zone to be served on the master as normal. This - could be done by editing ``named.conf``, or by running +- Set up the the member zone to be served on the primary as normal. This + can be done by editing ``named.conf`` or by running ``rndc addzone``. -- Add an entry to the catalog zone for the new member zone. This could +- Add an entry to the catalog zone for the new member zone. This can be done by editing the catalog zone's master file and running ``rndc reload``, or by updating the zone using ``nsupdate``. -The change to the catalog zone will be propagated from the master to all -slaves using the normal AXFR/IXFR mechanism. When the slave receives the -update to the catalog zone, it will detect the entry for the new member -zone, create an instance of of that zone on the slave server, and point +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 ``masters`` specified in the catalog zone data. The -newly created member zone is a normal slave zone, so BIND will -immediately initiate a transfer of zone contents from the master. Once -complete, the slave will start serving the member zone. +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 slave server requires nothing more than -deleting the member zone's entry in the catalog zone. The change to the -catalog zone is propagated to the slave server using the normal -AXFR/IXFR transfer mechanism. The slave server, on processing the -update, will notice that the member zone has been removed. It will stop -serving the zone and remove it from its list of configured zones. -(Removing the member zone from the master server has to be done in the -normal way, by editing the configuration file or running -``rndc delzone``.) +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 +``rndc delzone``. Configuring Catalog Zones ~~~~~~~~~~~~~~~~~~~~~~~~~ Catalog zones are configured with a ``catalog-zones`` statement in the -``options`` or ``view`` section of ``named.conf``. For example, +``options`` or ``view`` section of ``named.conf``. For example: :: @@ -108,46 +108,50 @@ Catalog zones are configured with a ``catalog-zones`` statement in the 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 slave zone. +configurations, it would be a secondary zone. The options following the zone name are not required, and may be -specified in any order: +specified in any order. -The ``default-masters`` option defines the default masters for member -zones listed in a catalog zone. This can be overridden by options within -a catalog zone. If no such options are included, then member zones will -transfer their contents from the servers listed in this option. +``default-masters`` + 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. -The ``in-memory`` option, if set to ``yes``, causes member zones to be -stored only in memory. This is functionally equivalent to configuring a -slave zone without a ``file``. option. The default is ``no``; member -zones' content will be stored locally in a file whose name is -automatically generated from the view name, catalog zone name, and -member zone name. +``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 ``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. -The ``zone-directory`` option causes local copies of member zones' -master files (if ``in-memory`` is not set to ``yes``) to be stored in -the specified directory. 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. +``zone-directory`` + This option causes local copies of member zones' + master 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. -The ``min-update-interval`` option sets the minimum interval between -processing of 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, then the -changes will not be carried out until this interval has elapsed. The -default is ``5`` seconds. +``min-update-interval`` + This option sets the minimum interval between + processing of 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 -``catalog-zones`` statement in a view will automatically turn on -``allow-new-zones`` for that view. (Note: this means ``rndc addzone`` -and ``rndc delzone`` will also work in any view that supports catalog -zones.) +``catalog-zones`` statement in a view automatically turns on +``allow-new-zones`` for that view. This means that ``rndc addzone`` +and ``rndc delzone`` also work in any view that supports catalog +zones. -Catalog Zone format +Catalog Zone Format ~~~~~~~~~~~~~~~~~~~ -A catalog zone is a regular DNS zone; therefore, it has to have a single +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 @@ -161,13 +165,13 @@ then a catalog zone may not be used by that server. version.catalog.example. IN TXT "1" Note that this record must have the domain name -version.catalog-zone-name. This illustrates how the meaning of data -stored in a catalog zone is indicated by the the domain name label +version.catalog-zone-name. The data +stored in a catalog zone is indicated by the domain name label immediately before the catalog zone domain. Catalog zone options can be set either globally for the whole catalog zone or for a single member zone. Global options override the settings -in the configuration file and member zone options override global +in the configuration file, and member zone options override global options. Global options are set at the apex of the catalog zone, e.g.: @@ -185,8 +189,8 @@ BIND currently supports the following options: masters.catalog.example. IN A 192.0.2.1 - This option defines a master server for the member zones - it can be - either an A or AAAA record. If multiple masters are set the order in + This option defines a primary server for the member zones - it can be + either an A or AAAA record. If multiple primaries are set, the order in which they are used is random. - A ``masters`` with a TSIG key defined: @@ -197,7 +201,7 @@ BIND currently supports the following options: label.masters.catalog.example. IN TXT "tsig_key_name" - This option defines a master server for the member zone with a TSIG + This option 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. @@ -211,9 +215,9 @@ BIND currently supports the following options: These options are the equivalents of ``allow-query`` and ``allow-transfer`` in a zone declaration in the ``named.conf`` - configuration file. The ACL is processed in order - if there's no - match to any rule the default policy is to deny access. For the - syntax of the APL RR see :rfc:`3123` + 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`. A member zone is added by including a ``PTR`` resource record in the ``zones`` sub-domain of the catalog zone. The record label is a @@ -236,12 +240,12 @@ options, but in the member zone subdomain: label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN TXT "tsig_key" allow-query.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN APL 1:10.0.0.0/24 -As would be expected, options defined for a specific zone override the +Options defined for a specific zone override the global options defined in the catalog zone. These in turn override the global options defined in the ``catalog-zones`` statement in the configuration file. -(Note that none of the global records an option will be inherited if any +Note that none of the global records for an option are inherited if any records are defined for that option for the specific zone. For example, -if the zone had a ``masters`` record of type A but not AAAA, then it -would *not* inherit the type AAAA record from the global option.) +if the zone had a ``masters`` record of type A but not AAAA, it +would *not* inherit the type AAAA record from the global option.