bind/doc/design/zone

<!--
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.
-->

			Zones

Overview

	Zones are the unit of delegation in the DNS and may go from holding
	RR's only at the zone top to holding the complete hierarchy (private
	roots zones).  Zones have an associated database which is the
	container for the RR sets that make up the zone.

	Zone have certain properties associated with them.

	* name
	* class
	* primary / secondary / stub / hint / cache / forward
	* serial number
	* signed / unsigned
	* update periods (refresh / retry) (secondary / stub)
	* last update time (slave / stub)
	* access restrictions
	* transfer restrictions (primary / slave)
	* update restictions (primary / slave)
	* expire period (slave / stub)
	* children => bottom
	* glue
	* rrsets / data
	* transfer "in" in progress
	* transfers "out" in progress
	* "current" check in progress
	* our primaries
	* primary server name (required to auto generate our primaries)
	* master file name
	* database name
	* database type
		* initially only master_file (BIND 4 & 8)
		* expanded axfr + ixfr
	* transaction logs
	* notification lists
		* NS's
		* static additional sites (stealth servers)
		* dynamically learned sites (soa queries)

	Zones have two types of versions associated with them.

	Type 1.
		The image of the "current" zone when a AXFR out is in progress.
		There may be several of these at once but they cease to need
		to exist once the AXFR's on this version has completed. These
		are maintained by the various database access methods.

	Type 2.
		These are virtual versions of the zone and are required to
		support IXFR requests.  While the entire contents of the old
		version does not need to be kept, a change log needs to be
		kept.  An index into this log would be useful in speeding
		up replies. These versions have an explicit expiry date.

		"How long are we going to keep them operationally?"
                While there are expriry dates based on last update /
                change time + expire.  In practice holding the deltas
                for a few refresh periods should be enough.  If the network
                and servers are up one is enough.

		"How are we going to generate them from a master file?"
                UPDATE should not be the only answer to this question.
                We need a tool that takes the current zone & new zone.
                Verifies the new zone, generates a delta and feeds this
                at named.  It could well be part of ndc but does not have
                to be.


	Zones need to have certain operations performed on them. The need to
	be:

	* loaded
	* unloaded
	* dumped
	* updated (UPDATE / IXFR)
	* copied out in full (AXFR) or as partial deltas (IXFR)
	* read from
	* validated
	* generate a delta between two given versions.
	* signed / resigned
	* maintenance
		validate current soa
		remove old deltas / consolidation
		purge stale rrsets (cache)
	* notification
		responding to
		generating

	While not strictly a nameserver function, bad delegation and bad
	slave setups are continual and ongoing sources of problems in the
	DNS.  Periodic checks to ensure parent and child servers agree on
	the list of nameservers and that slaves are tracking the changes
	made in the primary server's zone will allow problems in
	configurations to be identified earlier providing for a more stable
	DNS.

Compatibility:

	Zones are required to be configuration file compatible with
	BIND 8.x.

Types:

	typedef enum {
		dns_zone_none = 0,
		dns_zone_primary,
		dns_zone_secondary,
		dns_zone_mirror,
		dns_zone_stub,
		dns_zone_hint,
		dns_zone_cache,
		dns_zone_forward
	} dns_zonetypes_t;

	typedef struct dns_ixfr	dns_ixfr_t;

	struct dns_ixfr {
		unsigned int		magic;	/* IXFR */
		uint32_t		serial;
		time_t			expire;
		unsigned int		offset;
		ISC_LINK(dns_ixfr_t)	link;
	};

	struct dns_zone {
		unsigned int		magic;	/* ZONE */
		dns_name_t		name;
		dns_rdataclass_t	class;
		dns_zonetypes_t		type;
		dns_bt_t		top;
		uint32_t		version;
		uint32_t		serial;
		uint32_t		refresh;
		uint32_t		retry;
		uint32_t		serial;
		char			*masterfile;
		dns_acl_t		*access;
		dns_acl_t		*transfer;
		struct	{
			dns_acl_t	*acl;
			dns_scl_t	*scl;		/* tsig based acl */
		}			update;
		char			*database;
		ISC_LIST(dns_ixfr_t)	ixfr;
		...
	};

Operations:
Loading:

Functions:

    void
    dns_zone_init(dns_zone_t *zone, dns_rdataclass_t class, isc_mem_t *mxtc);

    void
    dns_zone_invalidate(dns_zone_t *zone);

    void
    dns_ixfr_init(dns_ixfr_t *ixfr, unsigned long serial, time_t expire);

    void
    dns_ixfr_invalidate(dns_ixfr_t *ixfr);

    dns_zone_axfrout(dns_zone_t *zone);

	Initiate outgoing zone transfer.

    dns_zone_axfrin(dns_zone_t *zone, isc_sockaddr_t *addr);

	Initiate transfer of the zone from the given server or the
	primary servers listed in the zone structure.

    dns_zone_locateprimary(dns_zone_t *zone);

	Working from the root zone locate the primary server for the zone.
	Used if primaries are not given in named.conf.

    dns_zone_locateservers(dns_zone_t *zone);

	Working from the root zone locate the servers for the zone.
	Primary server moved to first in list if in NS set.  Remove self
	from list.
	Used if primaries are not given in named.conf.

    dns_zone_notify(dns_zone_t *);

	Queue notify messages.

    dns_zone_checkparents(dns_zone_t *);

	check that the parent nameservers NS lists for this zone agree with
	the NS list this zone, check glue A records. Warn if not identical.
	This operation is performed on primary zones.

    dns_zone_checkchildren(dns_zone_t *);

	check that the child zones NS lists agree with the NS lists in this
	zone, check glue records.  Warn if not identical.

    dns_zone_checkservers(dns_zone_t *);

	check that all the listed servers for the zone agree on NS list and
	serial number. NOTE only errors which continue over several refresh
	periods to be reported.

    dns_zone_dump(dns_zone_t *, FILE *fp);

	Write the contents of the zone to the file associated with fp.

    dns_zone_validate(dns_zone_t *);

	Validate the zone contents using DNSSEC.

    dns_zone_tordatalist(dns_zone_t *zone, dns_rdatalist_t *list)

    dns_zone_addmaster(dns_zone_t *zone, isc_sockaddr_t *addr);

	Add addr to the set of primaries for the zone.

    dns_zone_clearmasters(dns_zone_t *zone);

	Clear the primary set.

    dns_zone_setreadacl(dns_zone_t *, dns_acl_t *)

    dns_zone_setxfracl(dns_zone_t *, dns_acl_t *)

    dns_zone_addnotify(dns_zone_t *, isc_sockaddr_t *addr, bool perm);

    dns_zone_clearnotify(dns_zone_t *)

    dns_zone_load(dns_zone_t *);

    dns_zone_consolidate(dns_zone_t *);

	Consolidate on disk copy of zone.