mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-09-02 15:45:25 +00:00
Code Issues Releases Wiki Activity

Merge branch '1888-text-edits-in-catz-rst' into 'master'

Browse Source 
Resolve "Text edits in catz.rst"

Closes #1888

See merge request isc-projects/bind9!3596
This commit is contained in:
Ondřej Surý
2020-06-01 07:02:44 +00:00
parent 5337e2e1f7 19ff2e2a79
commit b3931bfaa3
1 changed files with 83 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

162
doc/arm/catz.rst
View File

@@ -25,76 +25,76 @@ Catalog Zones
A "catalog zone" is a special DNS zone that contains a list of other A "catalog zone" is a special DNS zone that contains a list of other
zones to be served, along with their configuration parameters. Zones zones to be served, along with their configuration parameters. Zones
listed in a catalog zone are called "member zones". When a catalog zone listed in a catalog zone are called "member zones." When a catalog zone
is loaded or transferred to a slave server which supports this is loaded or transferred to a secondary server which supports this
functionality, the slave server will create the member zones functionality, the secondary server creates the member zones
automatically. When the catalog zone is updated (for example, to add or 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 changes are immediately put into effect. Because the catalog zone is a
normal DNS zone, these configuration changes can be propagated using the normal DNS zone, these configuration changes can be propagated using the
standard AXFR/IXFR zone transfer mechanism. standard AXFR/IXFR zone transfer mechanism.
Catalog zones' format and behavior are specified as an internet draft Catalog zones' format and behavior are specified as an Internet draft
for interoperability among DNS implementations. As of this release, the for interoperability among DNS implementations. The
latest revision of the DNS catalog zones draft can be found here: 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 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 ``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 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 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 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. zone that lists member zones that should be served by secondary servers.
When a slave server receives an update to the catalog zone, it adds, When a secondary server receives an update to the catalog zone, it adds,
removes, or reconfigures member zones based on the data received. 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 To use a catalog zone, it must first be set up as a normal zone on both the
master and the on slave servers that will be configured to use it. It primary and secondary servers that are configured to use it. It
must also be added to a ``catalog-zones`` list in the ``options`` or 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 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: 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 - Set up the the member zone to be served on the primary as normal. This
could be done by editing ``named.conf``, or by running can be done by editing ``named.conf`` or by running
``rndc addzone``. ``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 be done by editing the catalog zone's master file and running
``rndc reload``, or by updating the zone using ``nsupdate``. ``rndc reload``, or by updating the zone using ``nsupdate``.
The change to the catalog zone will be propagated from the master to all The change to the catalog zone is propagated from the primary to all
slaves using the normal AXFR/IXFR mechanism. When the slave receives the secondaries using the normal AXFR/IXFR mechanism. When the secondary receives the
update to the catalog zone, it will detect the entry for the new member update to the catalog zone, it detects the entry for the new member
zone, create an instance of of that zone on the slave server, and point 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 that instance to the ``masters`` specified in the catalog zone data. The
newly created member zone is a normal slave zone, so BIND will newly created member zone is a normal secondary zone, so BIND
immediately initiate a transfer of zone contents from the master. Once immediately initiates a transfer of zone contents from the primary. Once
complete, the slave will start serving the member zone. complete, the secondary starts serving the member zone.
Removing a member zone from a slave server requires nothing more than Removing a member zone from a secondary server requires only
deleting the member zone's entry in the catalog zone. The change to the 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 catalog zone is propagated to the secondary server using the normal
AXFR/IXFR transfer mechanism. The slave server, on processing the AXFR/IXFR transfer mechanism. The secondary server, on processing the
update, will notice that the member zone has been removed. It will stop update, notices that the member zone has been removed, stops
serving the zone and remove it from its list of configured zones. serving the zone, and removes it from its list of configured zones.
(Removing the member zone from the master server has to be done in the However, removing the member zone from the primary server must be done
normal way, by editing the configuration file or running by editing the configuration file or running
``rndc delzone``.) ``rndc delzone``.
Configuring Catalog Zones Configuring Catalog Zones
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
Catalog zones are configured with a ``catalog-zones`` statement in the 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 This statement specifies that the zone ``catalog.example`` is a catalog
zone. This zone must be properly configured in the same view. In most 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 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 ``default-masters``
zones listed in a catalog zone. This can be overridden by options within This option defines the default primaries for member
a catalog zone. If no such options are included, then member zones will zones listed in a catalog zone, and can be overridden by options within
transfer their contents from the servers listed in this option. 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 ``in-memory``
stored only in memory. This is functionally equivalent to configuring a This option, if set to ``yes``, causes member zones to be
slave zone without a ``file``. option. The default is ``no``; member stored only in memory. This is functionally equivalent to configuring a
zones' content will be stored locally in a file whose name is secondary zone without a ``file`` option. The default is ``no``; member
automatically generated from the view name, catalog zone name, and zones' content is stored locally in a file whose name is
member zone name. automatically generated from the view name, catalog zone name, and
member zone name.
The ``zone-directory`` option causes local copies of member zones' ``zone-directory``
master files (if ``in-memory`` is not set to ``yes``) to be stored in This option causes local copies of member zones'
the specified directory. The default is to store zone files in the master files to be stored in
server's working directory. A non-absolute pathname in the specified directory, if ``in-memory`` is not set to ``yes``. The default is to store zone files in the
``zone-directory`` is assumed to be relative to the working directory. 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 ``min-update-interval``
processing of updates to catalog zones, in seconds. If an update to a This option sets the minimum interval between
catalog zone (for example, via IXFR) happens less than processing of updates to catalog zones, in seconds. If an update to a
``min-update-interval`` seconds after the most recent update, then the catalog zone (for example, via IXFR) happens less than
changes will not be carried out until this interval has elapsed. The ``min-update-interval`` seconds after the most recent update, the
default is ``5`` seconds. 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 are defined on a per-view basis. Configuring a non-empty
``catalog-zones`` statement in a view will automatically turn on ``catalog-zones`` statement in a view automatically turns on
``allow-new-zones`` for that view. (Note: this means ``rndc addzone`` ``allow-new-zones`` for that view. This means that ``rndc addzone``
and ``rndc delzone`` will also work in any view that supports catalog and ``rndc delzone`` also work in any view that supports catalog
zones.) 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. ``SOA`` and at least one ``NS`` record.
A record stating the version of the catalog zone format is also 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" version.catalog.example. IN TXT "1"
Note that this record must have the domain name Note that this record must have the domain name
version.catalog-zone-name. This illustrates how the meaning of data version.catalog-zone-name. The data
stored in a catalog zone is indicated by the the domain name label stored in a catalog zone is indicated by the domain name label
immediately before the catalog zone domain. immediately before the catalog zone domain.
Catalog zone options can be set either globally for the whole catalog Catalog zone options can be set either globally for the whole catalog
zone or for a single member zone. Global options override the settings 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. options.
Global options are set at the apex of the catalog zone, e.g.: 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 masters.catalog.example. IN A 192.0.2.1
This option defines a master server for the member zones - it can be This option defines a primary server for the member zones - it can be
either an A or AAAA record. If multiple masters are set the order in either an A or AAAA record. If multiple primaries are set, the order in
which they are used is random. which they are used is random.
- A ``masters`` with a TSIG key defined: - 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" 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. key set. The TSIG key must be configured in the configuration file.
``label`` can be any valid DNS label. ``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 These options are the equivalents of ``allow-query`` and
``allow-transfer`` in a zone declaration in the ``named.conf`` ``allow-transfer`` in a zone declaration in the ``named.conf``
configuration file. The ACL is processed in order - if there's no 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 match to any rule, the default policy is to deny access. For the
syntax of the APL RR see :rfc:`3123` syntax of the APL RR, see :rfc:`3123`.
A member zone is added by including a ``PTR`` resource record in the 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 ``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" label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN TXT "tsig_key"
allow-query.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN APL 1:10.0.0.0/24 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 zone. These in turn override the
global options defined in the ``catalog-zones`` statement in the global options defined in the ``catalog-zones`` statement in the
configuration file. 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, 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 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.) would *not* inherit the type AAAA record from the global option.