mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-31 06:25:31 +00:00
Code Issues Releases Wiki Activity

Various text edits and fixes to the documentation

Browse Source
This commit is contained in:
Suzanne Goldlust
2020-06-08 15:33:45 +00:00
committed by Ondřej Surý
parent e1d42c5f87
commit 5aa5ad5abc
18 changed files with 600 additions and 768 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
doc/arm/advanced.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. Advanced:
Advanced DNS Features
@@ -42,7 +32,7 @@ The ``NOTIFY`` protocol is specified in :rfc:`1996`.
As a secondary zone can also be a primary to other secondaries, ``named``, by
default, sends ``NOTIFY`` messages for every zone it loads.
Specifying ``notify master-only;`` causes ``named`` to only send
Specifying ``notify primary-only;`` causes ``named`` to only send
``NOTIFY`` for primary zones that it loads.
.. _dynamic_update:
@@ -108,8 +98,8 @@ that the zone file of a dynamic zone is up-to-date is to run
``rndc stop``.
To make changes to a dynamic zone manually, follow these steps:
First, disable dynamic updates to the zone using
``rndc freeze zone``; this updates the zone's master file with the
first, disable dynamic updates to the zone using
``rndc freeze zone``. This updates the zone file with the
changes stored in its ``.jnl`` file. Then, edit the zone file. Finally, run
``rndc thaw zone`` to reload the changed zone and re-enable dynamic
updates.
@@ -156,21 +146,21 @@ Split DNS
---------
Setting up different views of the DNS space to internal
and external resolvers is usually referred to as a Split DNS setup.
There are several reasons an organization would want to set up its DNS
and external resolvers is usually referred to as a *split DNS* setup.
There are several reasons an organization might want to set up its DNS
this way.
One common reason to use Split DNS is to hide
One common reason to use split DNS is to hide
"internal" DNS information from "external" clients on the Internet.
There is some debate as to whether this is actually useful.
Internal DNS information leaks out in many ways (via email headers, for
example) and most savvy "attackers" can find the information they need
using other means. However, since listing addresses of internal servers
that external clients cannot possibly reach can result in connection
delays and other annoyances, an organization may choose to use Split
delays and other annoyances, an organization may choose to use split
DNS to present a consistent view of itself to the outside world.
Another common reason for setting up a Split DNS system is to allow
Another common reason for setting up a split DNS system is to allow
internal networks that are behind filters or in :rfc:`1918` space (reserved
IP space, as documented in :rfc:`1918`) to resolve DNS on the Internet.
Split DNS can also be used to allow mail from outside back into the
@@ -295,7 +285,7 @@ Internal DNS server config:
// sample primary zone
zone "site1.example.com" {
type master;
type primary;
file "m/site1.example.com";
// do normal iterative resolution (do not forward)
forwarders { };
@@ -305,16 +295,16 @@ Internal DNS server config:
// sample secondary zone
zone "site2.example.com" {
type slave;
type secondary;
file "s/site2.example.com";
masters { 172.16.72.3; };
primaries { 172.16.72.3; };
forwarders { };
allow-query { internals; externals; };
allow-transfer { internals; };
};
zone "site1.internal" {
type master;
type primary;
file "m/site1.internal";
forwarders { };
allow-query { internals; };
@@ -322,9 +312,9 @@ Internal DNS server config:
};
zone "site2.internal" {
type slave;
type secondary;
file "s/site2.internal";
masters { 172.16.72.3; };
primaries { 172.16.72.3; };
forwarders { };
allow-query { internals };
allow-transfer { internals; }
@@ -355,13 +345,13 @@ External (bastion host) DNS server configuration:
// sample secondary zone
zone "site1.example.com" {
type master;
type primary;
file "m/site1.foo.com";
allow-transfer { internals; externals; };
};
zone "site2.example.com" {
type slave;
type secondary;
file "s/site2.foo.com";
masters { another_bastion_host_maybe; };
allow-transfer { internals; externals; }
@@ -398,8 +388,8 @@ configuration syntax and the process of creating TSIG keys.
the tools included with BIND support it for sending messages to
``named``:
* :ref:`man_nsupdate` supports TSIG via the ``-k``, ``-l`` and ``-y`` command line options, or via the ``key`` command when running interactively.
* :ref:`man_dig` supports TSIG via the ``-k`` and ``-y`` command line options.
* :ref:`man_nsupdate` supports TSIG via the ``-k``, ``-l``, and ``-y`` command-line options, or via the ``key`` command when running interactively.
* :ref:`man_dig` supports TSIG via the ``-k`` and ``-y`` command-line options.
Generating a Shared Key
~~~~~~~~~~~~~~~~~~~~~~~
@@ -407,12 +397,12 @@ Generating a Shared Key
TSIG keys can be generated using the ``tsig-keygen`` command; the output
of the command is a ``key`` directive suitable for inclusion in
``named.conf``. The key name, algorithm, and size can be specified by
command line parameters; the defaults are "tsig-key", HMAC-SHA256, and
command-line parameters; the defaults are "tsig-key", HMAC-SHA256, and
256 bits, respectively.
Any string which is a valid DNS name can be used as a key name. For
example, a key to be shared between servers called ``host1`` and ``host2``
could be called "host1-host2.", and this key could be generated using:
could be called "host1-host2.", and this key can be generated using:
::
@@ -463,7 +453,7 @@ Instructing the Server to Use a Key
A server sending a request to another server must be told whether to use
a key, and if so, which key to use.
For example, a key may be specified for each server in the ``masters``
For example, a key may be specified for each server in the ``primaries``
statement in the definition of a secondary zone; in this case, all SOA QUERY
messages, NOTIFY messages, and zone transfer requests (AXFR or IXFR)
are signed using the specified key. Keys may also be specified in
@@ -499,7 +489,7 @@ TSIG keys may be specified in ACL definitions and ACL directives such as
``allow-query``, ``allow-transfer``, and ``allow-update``. The above key
would be denoted in an ACL element as ``key host1-host2.``
Here's an example of an ``allow-update`` directive using a TSIG key:
Here is an example of an ``allow-update`` directive using a TSIG key:
::
@@ -566,7 +556,7 @@ SIG(0)
BIND partially supports DNSSEC SIG(0) transaction signatures as
specified in :rfc:`2535` and :rfc:`2931`. SIG(0) uses public/private keys to
authenticate messages. Access control is performed in the same manner as
authenticate messages. Access control is performed in the same manner as with
TSIG keys; privileges can be granted or denied in ACL directives based
on the key name.
@@ -594,8 +584,7 @@ which must be followed. BIND 9 ships with several tools that are used in
this process, which are explained in more detail below. In all cases,
the ``-h`` option prints a full list of parameters. Note that the DNSSEC
tools require the keyset files to be in the working directory or the
directory specified by the ``-d`` option, and that the tools shipped
with BIND 9.2.x and earlier are not compatible with the current versions.
directory specified by the ``-d`` option.
There must also be communication with the administrators of the parent
and/or child zone to transmit keys. A zone's security status must be
@@ -603,8 +592,8 @@ indicated by the parent zone for a DNSSEC-capable resolver to trust its
data. This is done through the presence or absence of a ``DS`` record at
the delegation point.
For other servers to trust data in this zone, they must either be
statically configured with this zone's zone key or the zone key of
For other servers to trust data in this zone, they must be
statically configured with either this zone's zone key or the zone key of
another zone above this one in the DNS tree.
.. _generating_dnssec_keys:
@@ -640,7 +629,7 @@ To generate another key with the same properties but with a different
key tag, repeat the above command.
The ``dnssec-keyfromlabel`` program is used to get a key pair from a
crypto hardware and build the key files. Its usage is similar to
crypto hardware device and build the key files. Its usage is similar to
``dnssec-keygen``.
The public keys should be inserted into the zone file by including the
@@ -668,7 +657,7 @@ it is in a file called ``zone.child.example``:
One output file is produced: ``zone.child.example.signed``. This file
should be referenced by ``named.conf`` as the input file for the zone.
``dnssec-signzone`` also produces a keyset and dsset files. These are used
``dnssec-signzone`` also produces keyset and dsset files. These are used
to provide the parent zone administrators with the ``DNSKEYs`` (or their
corresponding ``DS`` records) that are the secure entry point to the zone.
@@ -829,7 +818,7 @@ Address Lookups Using AAAA Records
The IPv6 AAAA record is a parallel to the IPv4 A record, and, unlike the
deprecated A6 record, specifies the entire IPv6 address in a single
record. For example,
record. For example:
::
@@ -846,7 +835,7 @@ Address-to-Name Lookups Using Nibble Format
When looking up an address in nibble format, the address components are
simply reversed, just as in IPv4, and ``ip6.arpa.`` is appended to the
resulting name. For example, the following would provide reverse name
lookup for a host with address ``2001:db8::1``.
lookup for a host with address ``2001:db8::1``:
::

42
doc/arm/catz.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. _catz-info:
Catalog Zones
@@ -37,7 +27,7 @@ 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/.
https://datatracker.ietf.org/doc/draft-toorop-dnsop-dns-catalog-zones/ .
Principle of Operation
~~~~~~~~~~~~~~~~~~~~~~
@@ -68,14 +58,14 @@ To use the catalog zone feature to serve a new member zone:
``rndc addzone``.
- 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 zone file and running
``rndc reload``, or by updating the zone using ``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 ``masters`` specified in the catalog zone data. The
that instance to the ``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.
@@ -100,7 +90,7 @@ Catalog zones are configured with a ``catalog-zones`` statement in the
catalog-zones {
zone "catalog.example"
default-masters { 10.53.0.1; }
default-primaries { 10.53.0.1; }
in-memory no
zone-directory "catzones"
min-update-interval 10;
@@ -129,7 +119,7 @@ specified in any order.
``zone-directory``
This option causes local copies of member zones'
master files to be stored in
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.
@@ -165,7 +155,7 @@ 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. The data
``version.catalog-zone-name``. The data
stored in a catalog zone is indicated by the domain name label
immediately before the catalog zone domain.
@@ -178,27 +168,27 @@ Global options are set at the apex of the catalog zone, e.g.:
::
masters.catalog.example. IN AAAA 2001:db8::1
primaries.catalog.example. IN AAAA 2001:db8::1
BIND currently supports the following options:
- A simple ``masters`` definition:
- A simple ``primaries`` definition:
::
masters.catalog.example. IN A 192.0.2.1
primaries.catalog.example. IN A 192.0.2.1
This option defines a primary server for the member zones - it can be
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.
- A ``masters`` with a TSIG key defined:
- A ``primaries`` with a TSIG key defined:
::
label.masters.catalog.example. IN A 192.0.2.2
label.masters.catalog.example. IN TXT "tsig_key_name"
label.primaries.catalog.example. IN A 192.0.2.2
label.primaries.catalog.example. IN TXT "tsig_key_name"
This option defines a primary server for the member zone with a TSIG
@@ -235,9 +225,9 @@ options, but in the member zone subdomain:
::
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"
primaries.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN A 192.0.2.2
label.primaries.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN AAAA 2001:db8::2
label.primaries.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN TXT "tsig_key"
allow-query.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN APL 1:10.0.0.0/24
Options defined for a specific zone override the

72
doc/arm/configuration.rst
View File

@@ -8,22 +8,12 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. Configuration:
Name Server Configuration
=========================
In this chapter we provide some suggested configurations along with
In this chapter we provide some suggested configurations, along with
guidelines for their use. We suggest reasonable values for certain
option settings.
@@ -40,7 +30,7 @@ A Caching-only Name Server
The following sample configuration is appropriate for a caching-only
name server for use by clients internal to a corporation. All queries
from outside clients are refused using the ``allow-query`` option.
Alternatively, the same effect could be achieved using suitable firewall
The same effect can be achieved using suitable firewall
rules.
::
@@ -56,7 +46,7 @@ rules.
// Provide a reverse mapping for the loopback
// address 127.0.0.1
zone "0.0.127.in-addr.arpa" {
type master;
type primary;
file "localhost.rev";
notify no;
};
@@ -67,7 +57,7 @@ An Authoritative-only Name Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This sample configuration is for an authoritative-only server that is
the primary (master) server for ``example.com`` and a secondary (slave) server for the subdomain
the primary server for ``example.com`` and a secondary server for the subdomain
``eng.example.com``.
::
@@ -86,26 +76,26 @@ the primary (master) server for ``example.com`` and a secondary (slave) server f
// Provide a reverse mapping for the loopback
// address 127.0.0.1
zone "0.0.127.in-addr.arpa" {
type master;
type primary;
file "localhost.rev";
notify no;
};
// We are the master server for example.com
// We are the primary server for example.com
zone "example.com" {
type master;
type primary;
file "example.com.db";
// IP addresses of slave servers allowed to
// IP addresses of secondary servers allowed to
// transfer example.com
allow-transfer {
192.168.4.14;
192.168.5.53;
};
};
// We are a slave server for eng.example.com
// We are a secondary server for eng.example.com
zone "eng.example.com" {
type slave;
type secondary;
file "eng.example.com.bk";
// IP address of eng.example.com master server
// IP address of eng.example.com primary server
masters { 192.168.4.12; };
};
@@ -118,8 +108,8 @@ A primitive form of load balancing can be achieved in the DNS by using
multiple records (such as multiple A records) for one name.
For example, assuming three HTTP servers with network addresses of
10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the following
means that clients will connect to each machine one third of the time:
10.0.0.1, 10.0.0.2, and 10.0.0.3, a set of records such as the following
means that clients will connect to each machine one-third of the time:
+-----------+------+----------+----------+----------------------------+
| Name | TTL | CLASS | TYPE | Resource Record (RR) Data |
@@ -166,12 +156,12 @@ output format.
``dig``
``dig`` is the most versatile and complete of these lookup tools. It
has two modes: simple interactive mode for a single query, and batch
mode which executes a query for each in a list of several query
mode, which executes a query for each in a list of several query
lines. All query options are accessible from the command line.
``dig [@server] domain [query-type][query-class][+query-option][-dig-option][%comment]``
The usual simple use of ``dig`` will take the form
The usual simple use of ``dig`` takes the form
``dig @server domain query-type query-class``
@@ -183,7 +173,8 @@ output format.
default, it converts between host names and Internet addresses, but
its functionality can be extended with the use of options.
``host [-aCdlnrsTwv][-c class][-N ndots][-t type][-W timeout][-R retries][-m flag][-4][-6] hostname [server]``
``host [-aCdlnrsTwv][-c class][-N ndots][-t type][-W timeout][-R retries]
[-m flag][-4][-6] hostname [server]``
For more information and a list of available commands and options,
see the ``host`` man page.
@@ -191,7 +182,7 @@ output format.
``nslookup``
``nslookup`` has two modes: interactive and non-interactive.
Interactive mode allows the user to query name servers for
information about various hosts and domains or to print a list of
information about various hosts and domains, or to print a list of
hosts in a domain. Non-interactive mode is used to print just the
name and requested information for a host or domain.
@@ -225,10 +216,11 @@ server.
``named-checkconf [-jvz][-t directory][filename]``
``named-checkzone``
The ``named-checkzone`` program checks a master file for syntax and
The ``named-checkzone`` program checks a zone file for syntax and
consistency.
``named-checkzone [-djqvD][-c class][-o output][-t directory][-w directory][-k (ignore|warn|fail)][-n (ignore|warn|fail)][-W (ignore|warn)] zone [filename]``
``named-checkzone [-djqvD][-c class][-o output][-t directory][-w directory]
[-k (ignore|warn|fail)][-n (ignore|warn|fail)][-W (ignore|warn)] zone [filename]``
``named-compilezone``
This tool is similar to ``named-checkzone,`` but it always dumps the zone content
@@ -237,7 +229,7 @@ server.
``rndc``
The remote name daemon control (``rndc``) program allows the system
administrator to control the operation of a name server. If ``rndc`` is run
without any options, it will display a usage message as
without any options, it displays a usage message as
follows:
``rndc [-c config][-s server][-p port][-y key] command [command...]``
@@ -251,7 +243,7 @@ server.
with a configuration file. The default location for the ``rndc``
configuration file is ``/etc/rndc.conf``, but an alternate location
can be specified with the ``-c`` option. If the configuration file is
not found, ``rndc`` will also look in ``/etc/rndc.key`` (or whatever
not found, ``rndc`` also looks in ``/etc/rndc.key`` (or whatever
``sysconfdir`` was defined when the BIND build was configured). The
``rndc.key`` file is generated by running ``rndc-confgen -a`` as
described in :ref:`controls_statement_definition_and_usage`.
@@ -264,7 +256,7 @@ server.
The ``options`` statement has three clauses: ``default-server``,
``default-key``, and ``default-port``. ``default-server`` takes a
host name or address argument and represents the server that will be
host name or address argument and represents the server that is
contacted if no ``-s`` option is provided on the command line.
``default-key`` takes the name of a key as its argument, as defined
by a ``key`` statement. ``default-port`` specifies the port to which
@@ -275,13 +267,13 @@ server.
authenticating with ``named``. Its syntax is identical to the ``key``
statement in ``named.conf``. The keyword ``key`` is followed by a key
name, which must be a valid domain name, though it need not actually
be hierarchical; thus, a string like "``rndc_key``" is a valid name.
be hierarchical; thus, a string like ``rndc_key`` is a valid name.
The ``key`` statement has two clauses: ``algorithm`` and ``secret``.
While the configuration parser will accept any string as the argument
to the algorithm, currently only the strings ``hmac-md5``,
While the configuration parser accepts any string as the argument
to ``algorithm``, currently only the strings ``hmac-md5``,
``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``,
``hmac-sha384``, and ``hmac-sha512`` have any meaning. The secret
is a Base64 encoded string as specified in :rfc:`3548`.
is a Base64-encoded string as specified in :rfc:`3548`.
The ``server`` statement associates a key defined using the ``key``
statement with a server. The keyword ``server`` is followed by a host
@@ -309,7 +301,7 @@ server.
``$ rndc reload``
to connect to 127.0.0.1 port 953 and cause the name server to reload,
to connect to 127.0.0.1 port 953 and causes the name server to reload,
if a name server on the local machine is running with the following
controls statements:
@@ -322,16 +314,16 @@ server.
and it has an identical key statement for ``rndc_key``.
Running the ``rndc-confgen`` program conveniently creates a
Running the ``rndc-confgen`` program conveniently creates an
``rndc.conf`` file, and also displays the corresponding
``controls`` statement needed to add to ``named.conf``.
Alternatively, it is possible to run ``rndc-confgen -a`` to set up a
Alternatively, it is possible to run ``rndc-confgen -a`` to set up an
``rndc.key`` file and not modify ``named.conf`` at all.
Signals
~~~~~~~
Certain UNIX signals cause the name server to take specific actions, as
Certain Unix signals cause the name server to take specific actions, as
described in the following table. These signals can be sent using the
``kill`` command.

13
doc/arm/dlz.rst
View File

@@ -8,13 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. _dlz-info:
Dynamically Loadable Zones (DLZ)
@@ -37,7 +30,7 @@ dynamically at runtime, via the DLZ "dlopen" driver, which acts as a
generic wrapper around a shared object implementing the DLZ API. The
"dlopen" driver is linked into ``named`` by default, so configure
options are no longer necessary when using these dynamically linkable
drivers, but are still needed for the older drivers in
drivers; they are still needed for the older drivers in
``contrib/dlz/drivers``.
The DLZ module provides data to ``named`` in text
@@ -45,7 +38,7 @@ format, which is then converted to DNS wire format by ``named``. This
conversion, and the lack of any internal caching, places significant
limits on the query performance of DLZ modules. Consequently, DLZ is not
recommended for use on high-volume servers. However, it can be used in a
hidden primary (master) configuration, with secondaries retrieving zone updates via
hidden primary configuration, with secondaries retrieving zone updates via
AXFR. Note, however, that DLZ has no built-in support for DNS notify;
secondary servers are not automatically informed of changes to the zones in the
database.
@@ -129,7 +122,7 @@ querying client and alter its response on the basis of this
information. To demonstrate this feature, the example driver responds to
queries for "source-addr.``zonename``>/TXT" with the source address of
the query. Note, however, that this record will *not* be included in
AXFR or ANY responses. Normally, this feature would be used to alter
AXFR or ANY responses. Normally, this feature is used to alter
responses in some other fashion, e.g., by providing different address
records for a particular name depending on the network from which the
query arrived.

50
doc/arm/dnssec.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. _dnssec.dynamic.zones:
DNSSEC, Dynamic Zones, and Automatic Signing
@@ -26,7 +16,7 @@ DNSSEC, Dynamic Zones, and Automatic Signing
Converting From Insecure to Secure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Changing a zone from insecure to secure can be done in two ways: using a
A zone can be changed from insecure to secure in two ways: using a
dynamic DNS update, or via the ``auto-dnssec`` zone option.
For either method, ``named`` must be configured so that it can see
@@ -38,7 +28,7 @@ key-directory, as specified in ``named.conf``:
::
zone example.net {
type master;
type primary;
update-policy local;
file "dynamic/example.net/example.net";
key-directory "dynamic/example.net";
@@ -63,7 +53,7 @@ To insert the keys via dynamic update:
> send
While the update request completes almost immediately, the zone is
not completely signed until ``named`` has had time to walk the zone
not completely signed until ``named`` has had time to "walk" the zone
and generate the NSEC and RRSIG records. The NSEC record at the apex
is added last, to signal that there is a complete NSEC chain.
@@ -109,9 +99,9 @@ the keys' timing metadata. (See :ref:`man_dnssec-keygen` and
``named`` periodically searches the key directory for keys matching
the zone; if the keys' metadata indicates that any change should be
made to the zone, such as adding, removing, or revoking a key, then that
made to the zone - such as adding, removing, or revoking a key - then that
action is carried out. By default, the key directory is checked for
changes every 60 minutes; this period can be adjusted with the
changes every 60 minutes; this period can be adjusted with
``dnssec-loadkeys-interval``, up to a maximum of 24 hours. The
``rndc loadkeys`` command forces ``named`` to check for key updates immediately.
@@ -138,34 +128,34 @@ allow dynamic updates, by adding an ``allow-update`` or
``update-policy`` statement to the zone configuration. If this has not
been done, the configuration fails.
Private-type Records
Private Type Records
~~~~~~~~~~~~~~~~~~~~
The state of the signing process is signaled by private-type records
The state of the signing process is signaled by private type records
(with a default type value of 65534). When signing is complete, those
records with a nonzero initial octet have a nonzero value for the final octet.
records with a non-zero initial octet have a non-zero value for the final octet.
If the first octet of a private-type record is non-zero, the
If the first octet of a private type record is non-zero, the
record indicates either that the zone needs to be signed with the key matching
the record, or that all signatures that match the record should be
removed.
removed. Here are the meanings of the different values of the first octet:
algorithm (octet 1)
- algorithm (octet 1)
key id in network order (octet 2 and 3)
- key id in network order (octet 2 and 3)
removal flag (octet 4)
- removal flag (octet 4)
complete flag (octet 5)
- complete flag (octet 5)
Only records flagged as "complete" can be removed via dynamic update.
Attempts to remove other private type records are silently ignored.
Only records flagged as "complete" can be removed via dynamic update; attempts
to remove other private type records are silently ignored.
If the first octet is zero (this is a reserved algorithm number that
should never appear in a DNSKEY record), the record indicates
should never appear in a DNSKEY record), the record indicates that
changes to the NSEC3 chains are in progress. The rest of the record
contains an NSEC3PARAM record, while the flag field tells what operation to
perform based on the flag bits.
perform based on the flag bits:
0x01 OPTOUT
@@ -189,7 +179,7 @@ To perform key rollovers via dynamic update, the ``K*``
files for the new keys must be added so that ``named`` can find them.
The new DNSKEY RRs can then be added via dynamic update. ``named`` then causes the
zone to be signed with the new keys; when the signing is complete, the
private-type records are updated so that the last octet is non-zero.
private type records are updated so that the last octet is non-zero.
If this is for a KSK, the parent and any trust anchor
repositories of the new KSK must be informed.
@@ -208,7 +198,7 @@ Automatic Key Rollovers
~~~~~~~~~~~~~~~~~~~~~~~
When a new key reaches its activation date (as set by ``dnssec-keygen``
or ``dnssec-settime``), if the ``auto-dnssec`` zone option is set to
or ``dnssec-settime``), and if the ``auto-dnssec`` zone option is set to
``maintain``, ``named`` automatically carries out the key rollover.
If the key's algorithm has not previously been used to sign the zone,
then the zone is fully signed as quickly as possible. However, if

16
doc/arm/dyndb.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. _dyndb-info:
Dynamic Database (DynDB)
@@ -77,8 +67,8 @@ arguments in the ``dyndb`` statement:
dyndb sample "sample.so" { example.nil. arpa. };
In the above example, the module is configured to create a zone
"example.nil" which can answer queries and AXFR requests and accept
In the above example, the module is configured to create a zone,
"example.nil", which can answer queries and AXFR requests and accept
DDNS updates. At runtime, prior to any updates, the zone contains an
SOA, NS, and a single A record at the apex:
@@ -92,7 +82,7 @@ SOA, NS, and a single A record at the apex:
When the zone is updated dynamically, the DynDB module determines
whether the updated RR is an address (i.e., type A or AAAA) and if so,
whether the updated RR is an address (i.e., type A or AAAA); if so,
it automatically updates the corresponding PTR record in a reverse
zone. Note that updates are not stored permanently; all updates are lost when the
server is restarted.

10
doc/arm/general.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. General:
General DNS Reference Information

10
doc/arm/history.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. History:
A Brief History of the DNS and BIND

138
doc/arm/introduction.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. _Introduction:
Introduction
@@ -63,41 +53,29 @@ information related to BIND and the Domain Name System.
Conventions Used in This Document
---------------------------------
In this document, we use the following general typographic conventions:
In this document, we generally use ``Fixed Width`` text to indicate the
following types of information:
+-------------------------------------+--------------------------------+
| *To describe:* | *We use the style:* |
+-------------------------------------+--------------------------------+
| a pathname, filename, URL, | ``Fixed width`` |
| hostname, mailing list name, or new | |
| term or concept | |
+-------------------------------------+--------------------------------+
| literal user input | ``Fixed Width Bold`` |
+-------------------------------------+--------------------------------+
| program output | ``Fixed Width`` |
+-------------------------------------+--------------------------------+
- pathnames
- filenames
- URLs
- hostnames
- mailing list names
- new terms or concepts
- literal user input
- program output
- keywords
- variables
The following conventions are used in descriptions of the BIND
configuration file:
+-------------------------------------+--------------------------------+
| *To describe:* | *We use the style:* |
+-------------------------------------+--------------------------------+
| keywords | ``Fixed Width`` |
+-------------------------------------+--------------------------------+
| variables | ``Fixed Width`` |
+-------------------------------------+--------------------------------+
| Optional input | [Text is enclosed in square |
| | brackets] |
+-------------------------------------+--------------------------------+
Text in "quotes," **bold**, or *italics* is also used for emphasis or clarity.
.. _dns_overview:
The Domain Name System (DNS)
----------------------------
The purpose of this document is to explain the installation and upkeep
of the BIND (Berkeley Internet Name Domain) software package, and we
This document explains the installation and upkeep
of the BIND (Berkeley Internet Name Domain) software package. We
begin by reviewing the fundamentals of the Domain Name System (DNS) as
they relate to BIND.
@@ -130,12 +108,12 @@ written form as a string of labels listed from right to left and
separated by dots. A label need only be unique within its parent domain.
For example, a domain name for a host at the company *Example, Inc.*
could be ``ourhost.example.com``, where ``com`` is the top level domain
could be ``ourhost.example.com``, where ``com`` is the top-level domain
to which ``ourhost.example.com`` belongs, ``example`` is a subdomain of
``com``, and ``ourhost`` is the name of the host.
For administrative purposes, the name space is partitioned into areas
called *zones*, each starting at a node and extending down to the leaf
called *zones*, each starting at a node and extending down to the "leaf"
nodes or to nodes where other zones start. The data for each zone is
stored in a *name server*, which answers queries about the zone using
the *DNS protocol*.
@@ -161,8 +139,8 @@ tree except those which are delegated to other zones. A delegation point
is marked by one or more *NS records* in the parent zone, which should
be matched by equivalent NS records at the root of the delegated zone.
For instance, consider the ``example.com`` domain which includes names
such as ``host.aaa.example.com`` and ``host.bbb.example.com`` even
For instance, consider the ``example.com`` domain, which includes names
such as ``host.aaa.example.com`` and ``host.bbb.example.com``, even
though the ``example.com`` zone includes only delegations for the
``aaa.example.com`` and ``bbb.example.com`` zones. A zone can map
exactly to a single domain, but could also include only part of a
@@ -170,14 +148,14 @@ domain, the rest of which could be delegated to other name servers.
Every name in the DNS tree is a *domain*, even if it is *terminal*, that
is, has no *subdomains*. Every subdomain is a domain and every domain
except the root is also a subdomain. The terminology is not intuitive
and we suggest that you read :rfc:`1033`, :rfc:`1034` and :rfc:`1035` to gain a complete
and we suggest reading :rfc:`1033`, :rfc:`1034`, and :rfc:`1035` to gain a complete
understanding of this difficult and subtle topic.
Though BIND is called a "domain name server", it deals primarily in
terms of zones. The master and slave declarations in the ``named.conf``
file specify zones, not domains. When you ask some other site if it is
willing to be a slave server for your *domain*, you are actually asking
for slave service for some collection of zones.
Though BIND 9 is called a "domain name server," it deals primarily in
terms of zones. The primary and secondary declarations in the ``named.conf``
file specify zones, not domains. When BIND asks some other site if it is
willing to be a secondary server for a *domain*, it is actually asking
for secondary service for some collection of *zones*.
.. _auth_servers:
@@ -195,11 +173,11 @@ when debugging DNS configurations using tools like ``dig`` (:ref:`diagnostic_too
.. _primary_master:
The Primary Master
The Primary Server
^^^^^^^^^^^^^^^^^^
The authoritative server where the master copy of the zone data is
maintained is called the *primary master* server, or simply the
The authoritative server, where the main copy of the zone data is
maintained, is called the *primary* (formerly *master*) server, or simply the
*primary*. Typically it loads the zone contents from some local file
edited by humans or perhaps generated mechanically from some other local
file which is edited by humans. This file is called the *zone file* or
@@ -210,19 +188,19 @@ all, but may instead be the result of *dynamic update* operations.
.. _slave_server:
Slave Servers
^^^^^^^^^^^^^
Secondary Servers
^^^^^^^^^^^^^^^^^
The other authoritative servers, the *slave* servers (also known as
*secondary* servers) load the zone contents from another server using a
replication process known as a *zone transfer*. Typically the data are
transferred directly from the primary master, but it is also possible to
transfer it from another slave. In other words, a slave server may
itself act as a master to a subordinate slave server.
The other authoritative servers, the *secondary* servers (formerly known as
*slave* servers) load the zone contents from another server using a
replication process known as a *zone transfer*. Typically the data is
transferred directly from the primary, but it is also possible to
transfer it from another secondary. In other words, a secondary server may
itself act as a primary to a subordinate secondary server.
Periodically, the slave server must send a refresh query to determine
Periodically, the secondary server must send a refresh query to determine
whether the zone contents have been updated. This is done by sending a
query for the zone's SOA record and checking whether the SERIAL field
query for the zone's Start of Authority (SOA) record and checking whether the SERIAL field
has been updated; if so, a new transfer request is initiated. The timing
of these refresh queries is controlled by the SOA REFRESH and RETRY
fields, but can be overridden with the ``max-refresh-time``,
@@ -230,32 +208,32 @@ fields, but can be overridden with the ``max-refresh-time``,
options.
If the zone data cannot be updated within the time specified by the SOA
EXPIRE option (up to a hard-coded maximum of 24 weeks) then the slave
zone expires and will no longer respond to queries.
EXPIRE option (up to a hard-coded maximum of 24 weeks), the secondary
zone expires and no longer responds to queries.
.. _stealth_server:
Stealth Servers
^^^^^^^^^^^^^^^
Usually all of the zone's authoritative servers are listed in NS records
Usually, all of the zone's authoritative servers are listed in NS records
in the parent zone. These NS records constitute a *delegation* of the
zone from the parent. The authoritative servers are also listed in the
zone file itself, at the *top level* or *apex* of the zone. You can list
servers in the zone's top-level NS records that are not in the parent's
NS delegation, but you cannot list servers in the parent's delegation
that are not present at the zone's top level.
zone file itself, at the *top level* or *apex* of the zone.
Servers that are not in the parent's
NS delegation can be listed in the zone's top-level NS records, but servers that are not present at the zone's top level
cannot be listed in the parent's delegation.
A *stealth server* is a server that is authoritative for a zone but is
not listed in that zone's NS records. Stealth servers can be used for
keeping a local copy of a zone to speed up access to the zone's records
keeping a local copy of a zone, to speed up access to the zone's records
or to make sure that the zone is available even if all the "official"
servers for the zone are inaccessible.
A configuration where the primary master server itself is a stealth
A configuration where the primary server itself is a stealth
server is often referred to as a "hidden primary" configuration. One use
for this configuration is when the primary master is behind a firewall
and therefore unable to communicate directly with the outside world.
for this configuration is when the primary is behind a firewall
and is therefore unable to communicate directly with the outside world.
.. _cache_servers:
@@ -276,7 +254,7 @@ intimately connected, the terms *recursive server* and *caching server*
are often used synonymously.
The length of time for which a record may be retained in the cache of a
caching name server is controlled by the Time To Live (TTL) field
caching name server is controlled by the Time-To-Live (TTL) field
associated with each resource record.
.. _forwarder:
@@ -291,20 +269,20 @@ server, commonly referred to as a *forwarder*.
There may be one or more forwarders, and they are queried in turn until
the list is exhausted or an answer is found. Forwarders are typically
used when you do not wish all the servers at a given site to interact
directly with the rest of the Internet servers. A typical scenario would
involve a number of internal DNS servers and an Internet firewall.
Servers unable to pass packets through the firewall would forward to the
server that can do it, and that server would query the Internet DNS
servers on the internal server's behalf.
used when it is undesirable for all the servers at a given site to interact
directly with the rest of the Internet's servers. A typical scenario
involves internal DNS servers and an Internet firewall.
Servers unable to pass packets through the firewall forward their requests to the
server that can, and that server queries the Internet DNS
servers on the internal servers' behalf.
.. _multi_role:
Name Servers in Multiple Roles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The BIND name server can simultaneously act as a master for some zones,
a slave for other zones, and as a caching (recursive) server for a set
The BIND name server can simultaneously act as a primary for some zones,
a secondary for other zones, and as a caching (recursive) server for a set
of local clients.
However, since the functions of authoritative name service and

16
doc/arm/logging-categories.rst
View File

@@ -8,21 +8,11 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
``client``
Processing of client requests.
``cname``
Nameservers that are skipped due to them being a CNAME rather than A / AAAA records.
Name servers that are skipped for being a CNAME rather than A/AAAA records.
``config``
Configuration file parsing and processing.
@@ -79,13 +69,13 @@
``client ::1#62537 (www.example.net):``
``query: www.example.net IN AAAA -SE``
(The first part of this log message, showing the client address/port number and query name, is repeated in all subsequent log messages related to the same query.)
The first part of this log message, showing the client address/port number and query name, is repeated in all subsequent log messages related to the same query.
``query-errors``
Information about queries that resulted in some failure.
``rate-limit``
Start, periodic, and final notices of the rate limiting of a stream of responses that are logged at ``info`` severity in this category. These messages include a hash value of the domain name of the response and the name itself, except when there is insufficient memory to record the name for the final notice. The final notice is normally delayed until about one minute after rate limiting stops. A lack of memory can hurry the final notice, which is indicated by an initial asterisk (*). Various internal events are logged at debug 1 level and higher.
Start, periodic, and final notices of the rate limiting of a stream of responses that are logged at ``info`` severity in this category. These messages include a hash value of the domain name of the response and the name itself, except when there is insufficient memory to record the name for the final notice. The final notice is normally delayed until about one minute after rate limiting stops. A lack of memory can hurry the final notice, which is indicated by an initial asterisk (\*). Various internal events are logged at debug level 1 and higher.
Rate limiting of individual requests is logged in the ``query-errors`` category.

24
doc/arm/managed-keys.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. _rfc5011.support:
Dynamic Trust Anchor Management
@@ -49,14 +39,14 @@ RFC 5011-managed trust anchor takes note of the stand-by KSKs in the
zone's DNSKEY RRset, and stores them for future reference. The resolver
rechecks the zone periodically; after 30 days, if the new key is
still there, the key is accepted by the resolver as a valid
trust anchor for the zone. Any time after this 30-day acceptance timer
trust anchor for the zone. Anytime after this 30-day acceptance timer
has completed, the active KSK can be revoked, and the zone can be
"rolled over" to the newly accepted key.
The easiest way to place a stand-by key in a zone is to use the "smart
signing" features of ``dnssec-keygen`` and ``dnssec-signzone``. If a key
exists with a publication date in the past, but an activation date which is
unset or in the future, " ``dnssec-signzone -S``" includes the
unset or in the future, ``dnssec-signzone -S`` includes the
DNSKEY record in the zone but does not sign with it:
::
@@ -64,7 +54,7 @@ DNSKEY record in the zone but does not sign with it:
$ dnssec-keygen -K keys -f KSK -P now -A now+2y example.net
$ dnssec-signzone -S -K keys example.net
To revoke a key, the command ``dnssec-revoke`` has been added. This
To revoke a key, use the command ``dnssec-revoke``. This
adds the REVOKED bit to the key flags and regenerates the ``K*.key``
and ``K*.private`` files.
@@ -86,12 +76,12 @@ wrapping around at 65535. So, for example, the key
If two keys have IDs exactly 128 apart and one is revoked, the two
key IDs will collide, causing several problems. To prevent this,
``dnssec-keygen`` does not generate a new key if another key is present
which may collide. This checking only occurs if the new keys are
written to the same directory which holds all other keys in use for that
``dnssec-keygen`` does not generate a new key if another key
which may collide is present. This checking only occurs if the new keys are
written to the same directory that holds all other keys in use for that
zone.
Older versions of BIND 9 did not have this precaution. Exercise caution
Older versions of BIND 9 did not have this protection. Exercise caution
if using key revocation on keys that were generated by previous
releases, or if using keys stored in multiple directories or on multiple
machines.

54
doc/arm/manpages.rst
View File

@@ -13,36 +13,36 @@
Manual Pages
============
.. include:: ../../bin/rndc/rndc.conf.rst
.. include:: ../../bin/rndc/rndc.rst
.. include:: ../../bin/tools/nsec3hash.rst
.. include:: ../../bin/tools/dnstap-read.rst
.. include:: ../../bin/tools/named-nzd2nzf.rst
.. include:: ../../bin/tools/named-journalprint.rst
.. include:: ../../bin/tools/mdig.rst
.. include:: ../../bin/tools/named-rrchecker.rst
.. include:: ../../bin/tools/arpaname.rst
.. include:: ../../bin/dnssec/dnssec-revoke.rst
.. include:: ../../bin/dnssec/dnssec-cds.rst
.. include:: ../../bin/dnssec/dnssec-keygen.rst
.. include:: ../../bin/dnssec/dnssec-keyfromlabel.rst
.. include:: ../../bin/dnssec/dnssec-verify.rst
.. include:: ../../bin/dnssec/dnssec-settime.rst
.. include:: ../../bin/dnssec/dnssec-importkey.rst
.. include:: ../../bin/dnssec/dnssec-signzone.rst
.. include:: ../../bin/dnssec/dnssec-dsfromkey.rst
.. include:: ../../bin/plugins/filter-aaaa.rst
.. include:: ../../bin/confgen/ddns-confgen.rst
.. include:: ../../bin/confgen/rndc-confgen.rst
.. include:: ../../bin/delv/delv.rst
.. include:: ../../bin/nsupdate/nsupdate.rst
.. include:: ../../bin/dig/host.rst
.. include:: ../../bin/dig/dig.rst
.. include:: ../../bin/dig/nslookup.rst
.. include:: ../../bin/named/named.rst
.. include:: ../../bin/pkcs11/pkcs11-keygen.rst
.. include:: ../../bin/pkcs11/pkcs11-tokens.rst
.. include:: ../../bin/pkcs11/pkcs11-list.rst
.. include:: ../../bin/pkcs11/pkcs11-destroy.rst
.. include:: ../../bin/dnssec/dnssec-cds.rst
.. include:: ../../bin/dnssec/dnssec-dsfromkey.rst
.. include:: ../../bin/dnssec/dnssec-importkey.rst
.. include:: ../../bin/dnssec/dnssec-keyfromlabel.rst
.. include:: ../../bin/dnssec/dnssec-keygen.rst
.. include:: ../../bin/dnssec/dnssec-revoke.rst
.. include:: ../../bin/dnssec/dnssec-settime.rst
.. include:: ../../bin/dnssec/dnssec-signzone.rst
.. include:: ../../bin/dnssec/dnssec-verify.rst
.. include:: ../../bin/tools/dnstap-read.rst
.. include:: ../../bin/plugins/filter-aaaa.rst
.. include:: ../../bin/dig/host.rst
.. include:: ../../bin/tools/mdig.rst
.. include:: ../../bin/check/named-checkconf.rst
.. include:: ../../bin/check/named-checkzone.rst
.. include:: ../../bin/tools/named-journalprint.rst
.. include:: ../../bin/tools/named-nzd2nzf.rst
.. include:: ../../bin/tools/named-rrchecker.rst
.. include:: ../../bin/named/named.rst
.. include:: ../../bin/tools/nsec3hash.rst
.. include:: ../../bin/dig/nslookup.rst
.. include:: ../../bin/nsupdate/nsupdate.rst
.. include:: ../../bin/pkcs11/pkcs11-destroy.rst
.. include:: ../../bin/pkcs11/pkcs11-keygen.rst
.. include:: ../../bin/pkcs11/pkcs11-list.rst
.. include:: ../../bin/pkcs11/pkcs11-tokens.rst
.. include:: ../../bin/confgen/rndc-confgen.rst
.. include:: ../../bin/rndc/rndc.conf.rst
.. include:: ../../bin/rndc/rndc.rst

10
doc/arm/notes.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
Release Notes
=============

161
doc/arm/pkcs11.rst
View File

@@ -8,66 +8,56 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. _pkcs11:
PKCS#11 (Cryptoki) support
PKCS#11 (Cryptoki) Support
--------------------------
PKCS#11 (Public Key Cryptography Standard #11) defines a
Public Key Cryptography Standard #11 (PKCS#11) defines a
platform-independent API for the control of hardware security modules
(HSMs) and other cryptographic support devices.
BIND 9 is known to work with three HSMs: The AEP Keyper, which has been
tested with Debian Linux, Solaris x86 and Windows Server 2003; the
tested with Debian Linux, Solaris x86, and Windows Server 2003; the
Thales nShield, tested with Debian Linux; and the Sun SCA 6000
cryptographic acceleration board, tested with Solaris x86. In addition,
BIND can be used with all current versions of SoftHSM, a software-based
HSM simulator library produced by the OpenDNSSEC project.
PKCS#11 makes use of a "provider library": a dynamically loadable
PKCS#11 uses a "provider library": a dynamically loadable
library which provides a low-level PKCS#11 interface to drive the HSM
hardware. The PKCS#11 provider library comes from the HSM vendor, and it
is specific to the HSM to be controlled.
There are two available mechanisms for PKCS#11 support in BIND 9:
OpenSSL-based PKCS#11 and native PKCS#11. When using the first
mechanism, BIND uses a modified version of OpenSSL, which loads the
OpenSSL-based PKCS#11 and native PKCS#11. With OpenSSL-based PKCS#11,
BIND uses a modified version of OpenSSL, which loads the
provider library and operates the HSM indirectly; any cryptographic
operations not supported by the HSM can be carried out by OpenSSL
instead. The second mechanism enables BIND to bypass OpenSSL completely;
instead. Native PKCS#11 enables BIND to bypass OpenSSL completely;
BIND loads the provider library itself, and uses the PKCS#11 API to
drive the HSM directly.
Prerequisites
~~~~~~~~~~~~~
See the documentation provided by your HSM vendor for information about
installing, initializing, testing and troubleshooting the HSM.
See the documentation provided by the HSM vendor for information about
installing, initializing, testing, and troubleshooting the HSM.
Native PKCS#11
~~~~~~~~~~~~~~
Native PKCS#11 mode will only work with an HSM capable of carrying out
Native PKCS#11 mode only works with an HSM capable of carrying out
*every* cryptographic operation BIND 9 may need. The HSM's provider
library must have a complete implementation of the PKCS#11 API, so that
all these functions are accessible. As of this writing, only the Thales
nShield HSM and SoftHSMv2 can be used in this fashion. For other HSMs,
including the AEP Keyper, Sun SCA 6000 and older versions of SoftHSM,
including the AEP Keyper, Sun SCA 6000, and older versions of SoftHSM,
use OpenSSL-based PKCS#11. (Note: Eventually, when more HSMs become
capable of supporting native PKCS#11, it is expected that OpenSSL-based
PKCS#11 will be deprecated.)
To build BIND with native PKCS#11, configure as follows:
To build BIND with native PKCS#11, configure it as follows:
::
@@ -90,13 +80,13 @@ https://github.com/opendnssec/SoftHSMv2. It is a software library
developed by the OpenDNSSEC project (http://www.opendnssec.org) which
provides a PKCS#11 interface to a virtual HSM, implemented in the form
of a SQLite3 database on the local filesystem. It provides less security
than a true HSM, but it allows you to experiment with native PKCS#11
than a true HSM, but it allows users to experiment with native PKCS#11
when an HSM is not available. SoftHSMv2 can be configured to use either
OpenSSL or the Botan library to perform cryptographic functions, but
when using it for native PKCS#11 in BIND, OpenSSL is required.
By default, the SoftHSMv2 configuration file is prefix/etc/softhsm2.conf
(where prefix is configured at compile time). This location can be
By default, the SoftHSMv2 configuration file is ``prefix/etc/softhsm2.conf``
(where ``prefix`` is configured at compile time). This location can be
overridden by the SOFTHSM2_CONF environment variable. The SoftHSMv2
cryptographic store must be installed and initialized before using it
with BIND.
@@ -123,11 +113,11 @@ There are two "flavors" of PKCS#11 support provided by the patched
OpenSSL, one of which must be chosen at configuration time. The correct
choice depends on the HSM hardware:
- Use 'crypto-accelerator' with HSMs that have hardware cryptographic
- Use "crypto-accelerator" with HSMs that have hardware cryptographic
acceleration features, such as the SCA 6000 board. This causes
OpenSSL to run all supported cryptographic operations in the HSM.
- Use 'sign-only' with HSMs that are designed to function primarily as
- Use "sign-only" with HSMs that are designed to function primarily as
secure key storage devices, but lack hardware acceleration. These
devices are highly secure, but are not necessarily any faster at
cryptography than the system CPU MDASH often, they are slower. It is
@@ -145,14 +135,13 @@ methods work with OpenSSL 1.0.0 through 1.0.2.
.. note::
The OpenSSL patches as of this writing (January 2016) support
versions 0.9.8zh, 1.0.0t, 1.0.1q and 1.0.2f. ISC will provide updated
ISC provides updated
patches as new versions of OpenSSL are released. The version number
in the following examples is expected to change.
Before building BIND 9 with PKCS#11 support, it will be necessary to
Before building BIND 9 with PKCS#11 support, it is necessary to
build OpenSSL with the patch in place, and configure it with the path to
your HSM's PKCS#11 provider library.
the HSM's PKCS#11 provider library.
Patching OpenSSL
^^^^^^^^^^^^^^^^
@@ -180,7 +169,7 @@ Apply the patch from the BIND 9 release:
.. note::
The patch file may not be compatible with the "patch" utility on all
operating systems. You may need to install GNU patch.
operating systems; a GNU patch may need to be installed.
When building OpenSSL, place it in a non-standard location so that it
does not interfere with OpenSSL libraries elsewhere on the system. In
@@ -195,8 +184,8 @@ Building OpenSSL for the AEP Keyper on Linux
The AEP Keyper is a highly secure key storage device, but does not
provide hardware cryptographic acceleration. It can carry out
cryptographic operations, but it is probably slower than your system's
CPU. Therefore, we choose the 'sign-only' flavor when building OpenSSL.
cryptographic operations, but it is probably slower than the system's
CPU. Therefore, we choose the "sign-only" flavor when building OpenSSL.
The Keyper-specific PKCS#11 provider library is delivered with the
Keyper software. In this example, we place it /opt/pkcs11/usr/lib:
@@ -241,8 +230,8 @@ SoftHSM (version 1) is a software library developed by the OpenDNSSEC
project (http://www.opendnssec.org) which provides a PKCS#11 interface
to a virtual HSM, implemented in the form of a SQLite3 database on the
local filesystem. SoftHSM uses the Botan library to perform
cryptographic functions. Though less secure than a true HSM, it can
allow you to experiment with PKCS#11 when an HSM is not available.
cryptographic functions. Though less secure than a true HSM, it
allows users to experiment with PKCS#11 when an HSM is not available.
The SoftHSM cryptographic store must be installed and initialized before
using it with OpenSSL, and the SOFTHSM_CONF environment variable must
@@ -259,8 +248,8 @@ always point to the SoftHSM configuration file:
$ /opt/pkcs11/usr/bin/softhsm --init-token 0 --slot 0 --label softhsm
SoftHSM can perform all cryptographic operations, but since it only uses
your system CPU, there is no advantage to using it for anything but
signing. Therefore, we choose the 'sign-only' flavor when building
the system CPU, there is no advantage to using it for anything but
signing. Therefore, we choose the "sign-only" flavor when building
OpenSSL.
::
@@ -271,10 +260,10 @@ OpenSSL.
--pk11-flavor=sign-only \
--prefix=/opt/pkcs11/usr
After configuring, run "``make``" and "``make test``".
After configuring, run ``make`` and ``make test``.
Once you have built OpenSSL, run "``apps/openssl engine pkcs11``" to
confirm that PKCS#11 support was compiled in correctly. The output
Once OpenSSL is built, run ``apps/openssl engine pkcs11`` to
confirm that PKCS#11 support was compiled correctly. The output
should be one of the following lines, depending on the flavor selected:
::
@@ -287,11 +276,11 @@ Or:
(pkcs11) PKCS #11 engine support (crypto accelerator)
Next, run "``apps/openssl engine pkcs11 -t``". This will attempt to
Next, run ``apps/openssl engine pkcs11 -t``. This attempts to
initialize the PKCS#11 engine. If it is able to do so successfully, it
will report “``[ available ]``”.
reports ``[ available ]``.
If the output is correct, run "``make install``" which will install the
If the output is correct, run ``make install`` to install the
modified OpenSSL suite to ``/opt/pkcs11/usr``.
Configuring BIND 9 for Linux with the AEP Keyper
@@ -316,9 +305,9 @@ Configuring BIND 9 for Solaris with the SCA 6000
(For a 32-bit build, omit CC="cc -xarch=amd64".)
If configure complains about OpenSSL not working, you may have a
32/64-bit architecture mismatch. Or, you may have incorrectly specified
the path to OpenSSL (it should be the same as the --prefix argument to
If configure complains about OpenSSL not working, there may be a
32/64-bit architecture mismatch, or
the path to OpenSSL may have been incorrectly specified; it should be the same as the --prefix argument to
the OpenSSL Configure).
Configuring BIND 9 for SoftHSM
@@ -331,11 +320,11 @@ Configuring BIND 9 for SoftHSM
--with-openssl=/opt/pkcs11/usr \
--with-pkcs11=/opt/pkcs11/usr/lib/libsofthsm.so
After configuring, run "``make``", "``make test``" and
"``make install``".
After configuring, run ``make``, ``make test``, and
``make install``.
(Note: If "make test" fails in the "pkcs11" system test, you may have
forgotten to set the SOFTHSM_CONF environment variable.)
(Note: If ``make test`` fails in the "pkcs11" system test,
the SOFTHSM_CONF environment variable may not have been set.)
PKCS#11 Tools
~~~~~~~~~~~~~
@@ -346,16 +335,16 @@ BIND 9 includes a minimal set of tools to operate the HSM, including
to remove objects, and ``pkcs11-tokens`` to list available tokens.
In UNIX/Linux builds, these tools are built only if BIND 9 is configured
with the --with-pkcs11 option. (Note: If --with-pkcs11 is set to "yes",
rather than to the path of the PKCS#11 provider, then the tools will be
built but the provider will be left undefined. Use the -m option or the
with the ``--with-pkcs11`` option. (Note: If ``--with-pkcs11`` is set to ``yes``,
rather than to the path of the PKCS#11 provider, the tools are
built but the provider is left undefined. Use the -m option or the
PKCS11_PROVIDER environment variable to specify the path to the
provider.)
Using the HSM
~~~~~~~~~~~~~
For OpenSSL-based PKCS#11, we must first set up the runtime environment
For OpenSSL-based PKCS#11, the runtime environment must first be set up
so the OpenSSL and PKCS#11 libraries can be loaded:
::
@@ -363,7 +352,7 @@ so the OpenSSL and PKCS#11 libraries can be loaded:
$ export LD_LIBRARY_PATH=/opt/pkcs11/usr/lib:${LD_LIBRARY_PATH}
This causes ``named`` and other binaries to load the OpenSSL library
from ``/opt/pkcs11/usr/lib`` rather than from the default location. This
from ``/opt/pkcs11/usr/lib``, rather than from the default location. This
step is not necessary when using native PKCS#11.
Some HSMs require other environment variables to be set. For example,
@@ -381,8 +370,8 @@ uses the HSM, including ``pkcs11-keygen``, ``pkcs11-list``,
``pkcs11-destroy``, ``dnssec-keyfromlabel``, ``dnssec-signzone``,
``dnssec-keygen``, and ``named``.
We can now create and use keys in the HSM. In this case, we will create
a 2048 bit key and give it the label "sample-ksk":
We can now create and use keys in the HSM. In this case, we are creating
a 2048-bit key and giving it the label "sample-ksk":
::
@@ -399,7 +388,7 @@ To confirm that the key exists:
Before using this key to sign a zone, we must create a pair of BIND 9
key files. The "dnssec-keyfromlabel" utility does this. In this case, we
will be using the HSM key "sample-ksk" as the key-signing key for
are using the HSM key "sample-ksk" as the key-signing key for
"example.net":
::
@@ -408,16 +397,16 @@ will be using the HSM key "sample-ksk" as the key-signing key for
The resulting K*.key and K*.private files can now be used to sign the
zone. Unlike normal K\* files, which contain both public and private key
data, these files will contain only the public key data, plus an
data, these files contain only the public key data, plus an
identifier for the private key which remains stored within the HSM.
Signing with the private key takes place inside the HSM.
If you wish to generate a second key in the HSM for use as a
To generate a second key in the HSM for use as a
zone-signing key, follow the same procedure above, using a different
keylabel, a smaller key size, and omitting "-f KSK" from the
dnssec-keyfromlabel arguments:
keylabel, a smaller key size, and omitting ``-f KSK`` from the
``dnssec-keyfromlabel`` arguments:
(Note: When using OpenSSL-based PKCS#11 the label is an arbitrary string
(Note: When using OpenSSL-based PKCS#11, the label is an arbitrary string
which identifies the key. With native PKCS#11, the label is a PKCS#11
URI string which may include other details about the key and the HSM,
including its PIN. See :ref:`man_dnssec-keyfromlabel` for details.)
@@ -427,8 +416,8 @@ including its PIN. See :ref:`man_dnssec-keyfromlabel` for details.)
$ pkcs11-keygen -b 1024 -l sample-zsk
$ dnssec-keyfromlabel -l sample-zsk example.net
Alternatively, you may prefer to generate a conventional on-disk key,
using dnssec-keygen:
Alternatively, it may be preferable to generate a conventional on-disk key,
using ``dnssec-keygen``:
::
@@ -437,13 +426,13 @@ using dnssec-keygen:
This provides less security than an HSM key, but since HSMs can be slow
or cumbersome to use for security reasons, it may be more efficient to
reserve HSM keys for use in the less frequent key-signing operation. The
zone-signing key can be rolled more frequently, if you wish, to
zone-signing key can be rolled more frequently, if desired, to
compensate for a reduction in key security. (Note: When using native
PKCS#11, there is no speed advantage to using on-disk keys, as
cryptographic operations will be done by the HSM regardless.)
cryptographic operations are done by the HSM regardless.)
Now you can sign the zone. (Note: If not using the -S option to
``dnssec-signzone``, it will be necessary to add the contents of both
Now the zone can be signed. (Note: If not using the -S option to
``dnssec-signzone``, it is necessary to add the contents of both
``K*.key`` files to the zone master file before signing it.)
::
@@ -456,18 +445,18 @@ Now you can sign the zone. (Note: If not using the -S option to
Algorithm: NSEC3RSASHA1: ZSKs: 1, KSKs: 1 active, 0 revoked, 0 stand-by
example.net.signed
Specifying the engine on the command line
Specifying the Engine on the Command Line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When using OpenSSL-based PKCS#11, the "engine" to be used by OpenSSL can
be specified in ``named`` and all of the BIND ``dnssec-*`` tools by
using the "-E <engine>" command line option. If BIND 9 is built with the
--with-pkcs11 option, this option defaults to "pkcs11". Specifying the
engine will generally not be necessary unless for some reason you wish
to use a different OpenSSL engine.
using the "-E <engine>" command-line option. If BIND 9 is built with the
``--with-pkcs11`` option, this option defaults to "pkcs11". Specifying the
engine is generally not necessary unless
using a different OpenSSL engine.
If you wish to disable use of the "pkcs11" engine MDASH for
troubleshooting purposes, or because the HSM is unavailable MDASH set
To disable use of the "pkcs11" engine - for
troubleshooting purposes, or because the HSM is unavailable - set
the engine to the empty string. For example:
::
@@ -475,16 +464,16 @@ the engine to the empty string. For example:
$ dnssec-signzone -E '' -S example.net
This causes ``dnssec-signzone`` to run as if it were compiled without
the --with-pkcs11 option.
the ``--with-pkcs11`` option.
When built with native PKCS#11 mode, the "engine" option has a different
meaning: it specifies the path to the PKCS#11 provider library. This may
be useful when testing a new provider library.
Running named with automatic zone re-signing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Running ``named`` with Automatic Zone Re-signing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want ``named`` to dynamically re-sign zones using HSM keys,
For ``named`` to dynamically re-sign zones using HSM keys,
and/or to to sign new records inserted via nsupdate, then ``named`` must
have access to the HSM PIN. In OpenSSL-based PKCS#11, this is
accomplished by placing the PIN into the openssl.cnf file (in the above
@@ -505,9 +494,9 @@ Sample openssl.cnf:
[ pkcs11_section ]
PIN = <PLACE PIN HERE>
This will also allow the dnssec-\* tools to access the HSM without PIN
entry. (The pkcs11-\* tools access the HSM directly, not via OpenSSL, so
a PIN will still be required to use them.)
This also allows the ``dnssec-\*`` tools to access the HSM without PIN
entry. (The ``pkcs11-\*`` tools access the HSM directly, not via OpenSSL, so
a PIN is still required to use them.)
In native PKCS#11 mode, the PIN can be provided in a file specified as
an attribute of the key's label. For example, if a key had the label
@@ -517,5 +506,5 @@ be read from the file ``/etc/hsmpin``.
.. warning::
Placing the HSM's PIN in a text file in this manner may reduce the
security advantage of using an HSM. Be sure this is what you want to
do before configuring the system in this way.
security advantage of using an HSM. Use caution
before configuring the system in this way.

26
doc/arm/plugins.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. _module-info:
Plugins
@@ -60,32 +50,32 @@ Multiple ``plugin`` statements can be specified, to load different
plugins or multiple instances of the same plugin.
``parameters`` are passed as an opaque string to the plugin's initialization
routine. Configuration syntax will differ depending on the module.
routine. Configuration syntax differs depending on the module.
Developing Plugins
~~~~~~~~~~~~~~~~~~
Each plugin implements four functions:
- plugin_register
- ``plugin_register``
to allocate memory, configure a plugin instance, and attach to hook
points within
named
``named``
,
- plugin_destroy
- ``plugin_destroy``
to tear down the plugin instance and free memory,
- plugin_version
- ``plugin_version``
to check that the plugin is compatible with the current version of
the plugin API,
- plugin_check
- ``plugin_check``
to test syntactic correctness of the plugin parameters.
At various locations within the ``named`` source code, there are "hook
points" at which a plugin may register itself. When a hook point is
reached while ``named`` is running, it is checked to see whether any
plugins have registered themselves there; if so, the associated "hook
action" is called - this is a function within the plugin library. Hook
actions may examine the runtime state and make changes - for example,
action" - a function within the plugin library - is called. Hook
actions may examine the runtime state and make changes: for example,
modifying the answers to be sent back to a client or forcing a query to
be aborted. More details can be found in the file
``lib/ns/include/ns/hooks.h``.

621
doc/arm/reference.rst
View File

File diff suppressed because it is too large Load Diff

24
doc/arm/requirements.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. Requirements:
BIND Resource Requirements
@@ -32,7 +22,7 @@ DNS hardware requirements have traditionally been quite modest. For many
installations, servers that have been retired from active duty
have performed admirably as DNS servers.
However, the DNSSEC features of BIND 9 may prove to be quite CPU intensive,
However, the DNSSEC features of BIND 9 may be quite CPU-intensive,
so organizations that make heavy use of these features may wish
to consider larger systems for these applications. BIND 9 is fully
multithreaded, allowing full utilization of multiprocessor systems for
@@ -54,27 +44,27 @@ Memory Requirements
-------------------
Server memory must be sufficient to hold both the cache and the
zones loaded from disk. The ``max-cache-size`` option can be used to
zones loaded from disk. The ``max-cache-size`` option can
limit the amount of memory used by the cache, at the expense of reducing
cache hit rates and causing more DNS traffic. It is still good practice
to have enough memory to load all zone and cache data into memory;
unfortunately, the best way to determine this for a given installation
is to watch the name server in operation. After a few weeks the server
is to watch the name server in operation. After a few weeks, the server
process should reach a relatively stable size where entries are expiring
from the cache as fast as they are being inserted.
.. _intensive_env:
Name Server Intensive Environment Issues
Name Server-Intensive Environment Issues
----------------------------------------
For name server intensive environments, there are two alternative
For name server-intensive environments, there are two
configurations that may be used. The first is one where clients and any
second-level internal name servers query a main name server, which has
enough memory to build a large cache; this approach minimizes the
bandwidth used by external name lookups. The second alternative is to
set up second-level internal name servers to make queries independently.
In this configuration, none of the individual machines needs to have as
In this configuration, none of the individual machines need to have as
much memory or CPU power as in the first alternative, but this has the
disadvantage of making many more external queries, as none of the name
servers share their cached data.
@@ -84,7 +74,7 @@ servers share their cached data.
Supported Operating Systems
---------------------------
ISC BIND 9 compiles and runs on a large number of Unix-like operating
ISC BIND 9 compiles and runs on many Unix-like operating
systems and on Microsoft Windows Server 2012 R2, 2016, and Windows 10.
For an up-to-date list of supported systems, see the PLATFORMS.md file
in the top-level directory of the BIND 9 source distribution.

10
doc/arm/security.rst
View File

@@ -8,16 +8,6 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
..
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 http://mozilla.org/MPL/2.0/.
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
.. Security:
BIND 9 Security Considerations