Michał Kępień
dfdd3a8a2f
Every DocBook source document can be namespaced (DocBook 5) or
non-namespaced (DocBook 4). The set of XSL stylesheets used for
producing an output document can also be namespaced or non-namespaced.
Namespaced source documents should be used with namespaced stylesheets
and non-namespaced source documents should be used with non-namespaced
stylesheets. However, both stylesheet flavors contain processing rules
which allow them to be used interchangeably for any type of source
document.
Unfortunately, these processing rules became broken in version 1.79.1 of
the stylesheets, which means that non-namespaced source documents can no
longer be correctly transformed into man pages using namespaced
stylesheets and vice versa. This problem was fixed upstream [1], but no
released version of the XSL stylesheets contains that fix yet.
Back in 2016, this problem was reported as RT #43831 and allegedly fixed
in commit 1b8ce3b330. However, that fix
only helped for the non-namespaced version of the stylesheets - while
also breaking man page generation for the namespaced flavor.
Since using namespaced DocBook sources is the current best practice
(DocBook 5), make BIND DocBook sources namespaced again. When using
version 1.79.1 or 1.79.2 of the XSL stylesheets, care must be taken to
ensure namespaced stylesheets are used for generating BIND
documentation.
[1] https://github.com/docbook/xslt10-stylesheets/issues/109
278 lines
12 KiB
XML
278 lines
12 KiB
XML
<!--
|
|
- Copyright (C) Internet Systems Consortium, Inc. ("ISC")
|
|
-
|
|
- 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.
|
|
-->
|
|
|
|
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="catz-info"><info><title>Catalog Zones</title></info>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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/.
|
|
</para>
|
|
|
|
<section><info><title>Principle of Operation</title></info>
|
|
<para>
|
|
Normally, if a zone is to be served by a secondary server, the
|
|
<filename>named.conf</filename> file on the server must list the
|
|
zone, or the zone must be added using <command>rndc addzone</command>.
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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 <option>catalog-zones</option> list
|
|
in the <option>options</option> or <option>view</option> statement
|
|
in <filename>named.conf</filename>. This is comparable to the way
|
|
a policy zone is configured as a normal zone and also listed in
|
|
a <option>response-policy</option> statement.
|
|
</para>
|
|
<para>
|
|
To use the catalog zone feature to serve a new member zone:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Set up the the member zone to be served on the primary as normal.
|
|
This can be done by editing <filename>named.conf</filename>
|
|
or by running <command>rndc addzone</command>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
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 <command>rndc reload</command>, or by updating
|
|
the zone using <command>nsupdate</command>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
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 <option>masters</option> 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.
|
|
</para>
|
|
<para>
|
|
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
|
|
<command>rndc delzone</command>.)
|
|
</para>
|
|
</section>
|
|
|
|
<section><info><title>Configuring Catalog Zones</title></info>
|
|
<para>
|
|
Catalog zones are configured with a <command>catalog-zones</command>
|
|
statement in the <literal>options</literal> or <literal>view</literal>
|
|
section of <filename>named.conf</filename>. For example,
|
|
</para>
|
|
<screen>
|
|
catalog-zones {
|
|
zone "catalog.example"
|
|
default-masters { 10.53.0.1; }
|
|
in-memory no
|
|
zone-directory "catzones"
|
|
min-update-interval 10;
|
|
};
|
|
</screen>
|
|
<para>
|
|
This statement specifies that the zone
|
|
<literal>catalog.example</literal> is a catalog zone. This zone must be
|
|
properly configured in the same view. In most configurations, it would
|
|
be a secondary zone.
|
|
</para>
|
|
<para>
|
|
The options following the zone name are not required, and may be
|
|
specified in any order:
|
|
</para>
|
|
<para>
|
|
The <option>default-masters</option> 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.
|
|
</para>
|
|
<para>
|
|
The <option>in-memory</option> option, if set to <literal>yes</literal>,
|
|
causes member zones to be stored only in memory. This is functionally
|
|
equivalent to configuring a secondary zone without a <option>file</option>
|
|
option. The default is <literal>no</literal>; 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.
|
|
</para>
|
|
<para>
|
|
The <option>zone-directory</option> option causes local copies of
|
|
member zones' zone files to be stored in the specified directory,
|
|
if <option>in-memory</option> is not set to <literal>yes</literal>.
|
|
The default is to store zone files in the server's working directory.
|
|
A non-absolute pathname in <option>zone-directory</option> is
|
|
assumed to be relative to the working directory.
|
|
</para>
|
|
<para>
|
|
The <option>min-update-interval</option> 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 <option>min-update-interval</option> seconds after the most
|
|
recent update, the changes are not carried out until this
|
|
interval has elapsed. The default is <literal>5</literal> seconds.
|
|
</para>
|
|
<para>
|
|
Catalog zones are defined on a per-view basis. Configuring a non-empty
|
|
<option>catalog-zones</option> statement in a view automatically
|
|
turns on <option>allow-new-zones</option> for that view. This
|
|
means that <command>rndc addzone</command> and <command>rndc delzone</command>
|
|
also work in any view that supports catalog zones.
|
|
</para>
|
|
</section>
|
|
|
|
<section><info><title>Catalog Zone Format</title></info>
|
|
<para>
|
|
A catalog zone is a regular DNS zone; therefore, it must have a
|
|
single <literal>SOA</literal> and at least one <literal>NS</literal>
|
|
record.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<screen>
|
|
catalog.example. IN SOA . . 2016022901 900 600 86400 1
|
|
catalog.example. IN NS nsexample.
|
|
version.catalog.example. IN TXT "1"
|
|
</screen>
|
|
<para>
|
|
Note that this record must have the domain name
|
|
"version.<replaceable>catalog-zone-name</replaceable>".
|
|
The data stored in a catalog zone is indicated by the
|
|
the domain name label immediately before the catalog zone domain.
|
|
</para>
|
|
<para>
|
|
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
|
|
options.
|
|
</para>
|
|
<para>
|
|
Global options are set at the apex of the catalog zone, e.g.:
|
|
</para>
|
|
<screen>
|
|
masters.catalog.example. IN AAAA 2001:db8::1
|
|
</screen>
|
|
<para>BIND currently supports the following options:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A simple <option>masters</option> definition:</para>
|
|
<screen>
|
|
masters.catalog.example. IN A 192.0.2.1
|
|
</screen>
|
|
<para>
|
|
This option 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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A <option>masters</option> with a TSIG key defined:</para>
|
|
<screen>
|
|
label.masters.catalog.example. IN A 192.0.2.2
|
|
label.masters.catalog.example. IN TXT "tsig_key_name"
|
|
</screen>
|
|
<para>
|
|
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.
|
|
<option>label</option> can be any valid DNS label.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><option>allow-query</option> and
|
|
<option>allow-transfer</option> ACLs:</para>
|
|
<screen>
|
|
allow-query.catalog.example. IN APL 1:10.0.0.1/24
|
|
allow-transfer.catalog.example. IN APL !1:10.0.0.1/32 1:10.0.0.0/24
|
|
</screen>
|
|
<para>
|
|
These options are the equivalents of <option>allow-query</option>
|
|
and <option>allow-transfer</option> in a zone declaration in the
|
|
<filename>named.conf</filename> 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.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
A member zone is added by including a <literal>PTR</literal>
|
|
resource record in the <literal>zones</literal> sub-domain of the
|
|
catalog zone. The record label is a <literal>SHA-1</literal> hash
|
|
of the member zone name in wire format. The target of the PTR
|
|
record is the member zone name. For example, to add the member
|
|
zone <literal>domain.example</literal>:
|
|
</para>
|
|
<screen>
|
|
5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN PTR domain.example.
|
|
</screen>
|
|
<para>
|
|
The hash is necessary to identify options for a specific member
|
|
zone. The member zone-specific options are defined the same way as
|
|
global options, but in the member zone subdomain:
|
|
</para>
|
|
<screen>
|
|
masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN A 192.0.2.2
|
|
label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN AAAA 2001:db8::2
|
|
label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN TXT "tsig_key"
|
|
allow-query.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN APL 1:10.0.0.0/24
|
|
</screen>
|
|
<para>
|
|
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 <literal>catalog-zones</literal>
|
|
statement in the configuration file.
|
|
</para>
|
|
<para>
|
|
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 <literal>masters</literal> record of type
|
|
A but not AAAA, it would <emphasis>not</emphasis> inherit the
|
|
type AAAA record from the global option.
|
|
</para>
|
|
</section>
|
|
</section>
|