Adding upstream version 1:9.18.19.upstream/1%9.18.19upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 420 insertions, 0 deletions

diff --git a/doc/arm/advanced.inc.rst b/doc/arm/advanced.inc.rst
new file mode 100644
index 0000000..73202eb
--- /dev/null
+++ b/doc/arm/advanced.inc.rst
@@ -0,0 +1,420 @@
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0.  If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. _advanced:
+
+Advanced Configurations
+=======================
+
+.. _dynamic_update:
+
+Dynamic Update
+--------------
+
+Dynamic update is a method for adding, replacing, or deleting records in
+a primary server by sending it a special form of DNS messages. The format
+and meaning of these messages is specified in :rfc:`2136`.
+
+Dynamic update is enabled by including an :any:`allow-update` or an
+:any:`update-policy` clause in the :any:`zone` statement.
+
+If the zone's :any:`update-policy` is set to ``local``, updates to the zone
+are permitted for the key ``local-ddns``, which is generated by
+:iscman:`named` at startup. See :ref:`dynamic_update_policies` for more details.
+
+Dynamic updates using Kerberos-signed requests can be made using the
+TKEY/GSS protocol, either by setting the :any:`tkey-gssapi-keytab` option
+or by setting both the :any:`tkey-gssapi-credential` and
+:any:`tkey-domain` options. Once enabled, Kerberos-signed requests are
+matched against the update policies for the zone, using the Kerberos
+principal as the signer for the request.
+
+Updating of secure zones (zones using DNSSEC) follows :rfc:`3007`: RRSIG,
+NSEC, and NSEC3 records affected by updates are automatically regenerated
+by the server using an online zone key. Update authorization is based on
+transaction signatures and an explicit server policy.
+
+.. _journal:
+
+The Journal File
+~~~~~~~~~~~~~~~~
+
+All changes made to a zone using dynamic update are stored in the zone's
+journal file. This file is automatically created by the server when the
+first dynamic update takes place. The name of the journal file is formed
+by appending the extension ``.jnl`` to the name of the corresponding
+zone file unless specifically overridden. The journal file is in a
+binary format and should not be edited manually.
+
+The server also occasionally writes ("dumps") the complete contents
+of the updated zone to its zone file. This is not done immediately after
+each dynamic update because that would be too slow when a large zone is
+updated frequently. Instead, the dump is delayed by up to 15 minutes,
+allowing additional updates to take place. During the dump process,
+transient files are created with the extensions ``.jnw`` and
+``.jbk``; under ordinary circumstances, these are removed when the
+dump is complete, and can be safely ignored.
+
+When a server is restarted after a shutdown or crash, it replays the
+journal file to incorporate into the zone any updates that took place
+after the last zone dump.
+
+Changes that result from incoming incremental zone transfers are also
+journaled in a similar way.
+
+The zone files of dynamic zones cannot normally be edited by hand
+because they are not guaranteed to contain the most recent dynamic
+changes; those are only in the journal file. The only way to ensure
+that the zone file of a dynamic zone is up-to-date is to run
+:option:`rndc stop`.
+
+To make changes to a dynamic zone manually, follow these steps:
+first, disable dynamic updates to the zone using
+:option:`rndc freeze zone <rndc freeze>`. This updates the zone file with the
+changes stored in its ``.jnl`` file. Then, edit the zone file. Finally, run
+:option:`rndc thaw zone <rndc thaw>` to reload the changed zone and re-enable dynamic
+updates.
+
+:option:`rndc sync zone <rndc sync>` updates the zone file with changes from the
+journal file without stopping dynamic updates; this may be useful for
+viewing the current zone state. To remove the ``.jnl`` file after
+updating the zone file, use :option:`rndc sync -clean <rndc sync>`.
+
+.. _notify:
+
+NOTIFY
+------
+
+DNS NOTIFY is a mechanism that allows primary servers to notify their
+secondary servers of changes to a zone's data. In response to a NOTIFY message
+from a primary server, the secondary checks to see that its version of
+the zone is the current version and, if not, initiates a zone transfer.
+
+For more information about DNS NOTIFY, see the description of the
+:namedconf:ref:`notify` and :namedconf:ref`also-notify` statements.
+The NOTIFY protocol is specified in :rfc:`1996`.
+
+.. note::
+
+   As a secondary zone can also be a primary to other secondaries, :iscman:`named`, by
+   default, sends NOTIFY messages for every zone it loads.
+
+.. _incremental_zone_transfers:
+
+Incremental Zone Transfers (IXFR)
+---------------------------------
+
+The incremental zone transfer (IXFR) protocol is a way for secondary servers
+to transfer only changed data, instead of having to transfer an entire
+zone. The IXFR protocol is specified in :rfc:`1995`.
+
+When acting as a primary server, BIND 9 supports IXFR for those zones where the
+necessary change history information is available. These include primary
+zones maintained by dynamic update and secondary zones whose data was
+obtained by IXFR. For manually maintained primary zones, and for secondary
+zones obtained by performing a full zone transfer (AXFR), IXFR is
+supported only if the option :any:`ixfr-from-differences` is set to
+``yes``.
+
+When acting as a secondary server, BIND 9 attempts to use IXFR unless it is
+explicitly disabled. For more information about disabling IXFR, see the
+description of the :any:`request-ixfr` clause of the :namedconf:ref:`server` statement.
+
+When a secondary server receives a zone via AXFR, it creates a new copy of the
+zone database and then swaps it into place; during the loading process, queries
+continue to be served from the old database with no interference. When receiving
+a zone via IXFR, however, changes are applied to the running zone, which may
+degrade query performance during the transfer. If a server receiving an IXFR
+request determines that the response size would be similar in size to an AXFR
+response, it may wish to send AXFR instead. The threshold at which this
+determination is made can be configured using the
+:any:`max-ixfr-ratio` option.
+
+.. _split_dns:
+
+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 might want to set up its DNS
+this way.
+
+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
+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
+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
+internal network.
+
+.. _split_dns_sample:
+
+Example Split DNS Setup
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's say a company named *Example, Inc.* (``example.com``) has several
+corporate sites that have an internal network with reserved Internet
+Protocol (IP) space and an external demilitarized zone (DMZ), or
+"outside" section of a network, that is available to the public.
+
+Example, Inc. wants its internal clients to be able to resolve
+external hostnames and to exchange mail with people on the outside. The
+company also wants its internal resolvers to have access to certain
+internal-only zones that are not available at all outside of the
+internal network.
+
+To accomplish this, the company sets up two sets of name
+servers. One set is on the inside network (in the reserved IP
+space) and the other set is on bastion hosts, which are "proxy"
+hosts in the DMZ that can talk to both sides of its network.
+
+The internal servers are configured to forward all queries, except
+queries for ``site1.internal``, ``site2.internal``,
+``site1.example.com``, and ``site2.example.com``, to the servers in the
+DMZ. These internal servers have complete sets of information for
+``site1.example.com``, ``site2.example.com``, ``site1.internal``, and
+``site2.internal``.
+
+To protect the ``site1.internal`` and ``site2.internal`` domains, the
+internal name servers must be configured to disallow all queries to
+these domains from any external hosts, including the bastion hosts.
+
+The external servers, which are on the bastion hosts, are configured
+to serve the "public" version of the ``site1.example.com`` and ``site2.example.com``
+zones. This could include things such as the host records for public
+servers (``www.example.com`` and ``ftp.example.com``) and mail exchange
+(MX) records (``a.mx.example.com`` and ``b.mx.example.com``).
+
+In addition, the public ``site1.example.com`` and ``site2.example.com`` zones should
+have special MX records that contain wildcard (``*``) records pointing to
+the bastion hosts. This is needed because external mail servers
+have no other way of determining how to deliver mail to those internal
+hosts. With the wildcard records, the mail is delivered to the
+bastion host, which can then forward it on to internal hosts.
+
+Here's an example of a wildcard MX record:
+
+::
+
+   *   IN MX 10 external1.example.com.
+
+Now that they accept mail on behalf of anything in the internal network,
+the bastion hosts need to know how to deliver mail to internal
+hosts. The resolvers on the bastion
+hosts need to be configured to point to the internal name servers
+for DNS resolution.
+
+Queries for internal hostnames are answered by the internal servers,
+and queries for external hostnames are forwarded back out to the DNS
+servers on the bastion hosts.
+
+For all of this to work properly, internal clients need to be
+configured to query *only* the internal name servers for DNS queries.
+This could also be enforced via selective filtering on the network.
+
+If everything has been set properly, Example, Inc.'s internal clients
+are now able to:
+
+-  Look up any hostnames in the ``site1.example.com`` and ``site2.example.com``
+   zones.
+
+-  Look up any hostnames in the ``site1.internal`` and
+   ``site2.internal`` domains.
+
+-  Look up any hostnames on the Internet.
+
+-  Exchange mail with both internal and external users.
+
+Hosts on the Internet are able to:
+
+-  Look up any hostnames in the ``site1.example.com`` and ``site2.example.com``
+   zones.
+
+-  Exchange mail with anyone in the ``site1.example.com`` and ``site2.example.com``
+   zones.
+
+Here is an example configuration for the setup just described above.
+Note that this is only configuration information; for information on how
+to configure the zone files, see :ref:`sample_configuration`.
+
+Internal DNS server config:
+
+::
+
+
+   acl internals { 172.16.72.0/24; 192.168.1.0/24; };
+
+   acl externals { bastion-ips-go-here; };
+
+   options {
+       ...
+       ...
+       forward only;
+       // forward to external servers
+       forwarders {
+       bastion-ips-go-here;
+       };
+       // sample allow-transfer (no one)
+       allow-transfer { none; };
+       // restrict query access
+       allow-query { internals; externals; };
+       // restrict recursion
+       allow-recursion { internals; };
+       ...
+       ...
+   };
+
+   // sample primary zone
+   zone "site1.example.com" {
+     type primary;
+     file "m/site1.example.com";
+     // do normal iterative resolution (do not forward)
+     forwarders { };
+     allow-query { internals; externals; };
+     allow-transfer { internals; };
+   };
+
+   // sample secondary zone
+   zone "site2.example.com" {
+     type secondary;
+     file "s/site2.example.com";
+     primaries { 172.16.72.3; };
+     forwarders { };
+     allow-query { internals; externals; };
+     allow-transfer { internals; };
+   };
+
+   zone "site1.internal" {
+     type primary;
+     file "m/site1.internal";
+     forwarders { };
+     allow-query { internals; };
+     allow-transfer { internals; }
+   };
+
+   zone "site2.internal" {
+     type secondary;
+     file "s/site2.internal";
+     primaries { 172.16.72.3; };
+     forwarders { };
+     allow-query { internals };
+     allow-transfer { internals; }
+   };
+
+External (bastion host) DNS server configuration:
+
+::
+
+   acl internals { 172.16.72.0/24; 192.168.1.0/24; };
+
+   acl externals { bastion-ips-go-here; };
+
+   options {
+     ...
+     ...
+     // sample allow-transfer (no one)
+     allow-transfer { none; };
+     // default query access
+     allow-query { any; };
+     // restrict cache access
+     allow-query-cache { internals; externals; };
+     // restrict recursion
+     allow-recursion { internals; externals; };
+     ...
+     ...
+   };
+
+   // sample secondary zone
+   zone "site1.example.com" {
+     type primary;
+     file "m/site1.foo.com";
+     allow-transfer { internals; externals; };
+   };
+
+   zone "site2.example.com" {
+     type secondary;
+     file "s/site2.foo.com";
+     primaries { another_bastion_host_maybe; };
+     allow-transfer { internals; externals; }
+   };
+
+In the ``resolv.conf`` (or equivalent) on the bastion host(s):
+
+::
+
+   search ...
+   nameserver 172.16.72.2
+   nameserver 172.16.72.3
+   nameserver 172.16.72.4
+
+.. _ipv6:
+
+IPv6 Support in BIND 9
+----------------------
+
+BIND 9 fully supports all currently defined forms of IPv6 name-to-address
+and address-to-name lookups. It also uses IPv6 addresses to
+make queries when running on an IPv6-capable system.
+
+For forward lookups, BIND 9 supports only AAAA records. :rfc:`3363`
+deprecated the use of A6 records, and client-side support for A6 records
+was accordingly removed from BIND 9. However, authoritative BIND 9 name
+servers still load zone files containing A6 records correctly, answer
+queries for A6 records, and accept zone transfer for a zone containing
+A6 records.
+
+For IPv6 reverse lookups, BIND 9 supports the traditional "nibble"
+format used in the ``ip6.arpa`` domain, as well as the older, deprecated
+``ip6.int`` domain. Older versions of BIND 9 supported the "binary label"
+(also known as "bitstring") format, but support of binary labels has
+been completely removed per :rfc:`3363`. Many applications in BIND 9 do not
+understand the binary label format at all anymore, and return an
+error if one is given. In particular, an authoritative BIND 9 name server will
+not load a zone file containing binary labels.
+
+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:
+
+::
+
+   $ORIGIN example.com.
+   host            3600    IN      AAAA    2001:db8::1
+
+Use of IPv4-in-IPv6 mapped addresses is not recommended. If a host has
+an IPv4 address, use an A record, not a AAAA, with
+``::ffff:192.168.42.1`` as the address.
+
+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 commands produce a reverse name
+lookup for a host with address ``2001:db8::1``:
+
+::
+
+   $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa.
+   1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0  14400   IN    PTR    (
+                       host.example.com. )