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

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

1 files changed, 256 insertions, 0 deletions

diff --git a/contrib/dlz/example/README b/contrib/dlz/example/README
new file mode 100644
index 0000000..d36fba4
--- /dev/null
+++ b/contrib/dlz/example/README
@@ -0,0 +1,256 @@
+<!--
+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.
+-->
+
+OVERVIEW:
+
+DLZ (Dynamically Loadable Zones) is an extension to BIND 9 that
+allows zone data to be retrieved directly from an external database.
+There is no required format or schema.  DLZ drivers exist for several
+different database backends including PostgreSQL, MySQL, and LDAP and
+can be written for any other.
+
+Historically, DLZ drivers had to be statically linked with the named
+binary and were turned on via a configure option at compile time (for
+example, "configure --with-dlz-ldap").  Currently, the drivers provided
+in the BIND 9 tarball in contrib/dlz/drivers are still linked this way.
+
+However, as of BIND 9.8, it is also possible to link some DLZ modules
+dynamically at runtime, via the DLZ "dlopen" driver, which acts as a
+generic wrapper around a shared object that implements the DLZ API.  The
+"dlopen" driver is linked into named by default, so configure options are
+no longer necessary unless using older DLZ drivers.
+
+When the DLZ module provides data to named, it does so in text format.
+The response is 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
+master configuration, with slaves retrieving zone updates via AXFR.
+(Note, however, that DLZ has no built-in support for DNS notify; slaves
+are not automatically informed of changes to the zones in the database.)
+
+CONFIGURING DLZ:
+
+A DLZ database is configured with a "dlz" statement in named.conf.
+
+    dlz example {
+        database "dlopen driver.so <args>";
+        search yes;
+    };
+
+This specifies a DLZ module to search when answering queries; the module
+is implemented in "driver.so" and is loaded at runtime by the dlopen DLZ
+driver.  Multiple "dlz" statements can be specified; when answering a
+query, all DLZ modules with the "search" option set to "yes" will be
+checked for an answer, and the best available answer will be returned
+to the client.
+
+The "search" option in this example can be omitted, as "yes" is the
+default value.  If it is set to "no", then this DLZ module is *not*
+searched for best-match when a query is received.  Instead, zones in
+this DLZ must be separately specified in a zone statement.  This can
+be useful when conventional zone semantics are desired but you wish
+to use a different back-end storage mechanism than the standard zone
+database.  For example, to use a DLZ module for an NXDOMAIN redirection
+zone:
+
+    dlz other {
+        database "dlopen driver.so <args>";
+        search no;
+    };
+
+    zone "." {
+        type redirect;
+        dlz other;
+    };
+
+EXAMPLE DRIVER:
+
+This directory contains an example of an externally-lodable DLZ module,
+dlz_example.c, which demonstrates the features of the DLZ API.  It sets up
+a single zone, whose name is configured in named.conf.  The zone can answer
+queries and AXFR requests, and accept DDNS updates.
+
+By default, at runtime, the zone implemented by this driver will contain
+an SOA, NS, and a single A record at the apex.  If configured in named.conf
+to use the name "example.nil", then, the zone will look like this:
+
+ example.nil.  3600    IN      SOA     example.nil. hostmaster.example.nil. (
+                                               123 900 600 86400 3600
+                                       )
+ example.nil.  3600    IN      NS      example.nil.
+ example.nil.  1800    IN      A       10.53.0.1
+
+The driver is also capable of retrieving information about the querying
+client, and altering 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 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.)
+
+DYNAMIC UPDATES AND TRANSACTIONS:
+
+If a DLZ module wants to implement dynamic DNS updates (DDNS), the
+normal calling sequence is
+ - dlz_newversion (start a 'transaction')
+ - dlz_addrdataset (add records)
+ - dlz_subrdataset (remove records)
+ - dlz_closeversion (end a 'transaction')
+
+However, BIND may also query the database during the transaction
+(e.g., to check prerequisites), and your DLZ might need to know whether
+the lookup is against the pre-existing data, or the new data.
+dlz_lookup() doesn't give you access to the 'versionp' pointer
+directly, so it must be passed via 'clientinfo' structure if
+it is needed.
+
+The dlz_example.c code has sample code to show how to get the 'versionp'
+pointer from within dlz_lookup(). If it's set to NULL, we query
+the standard database; if non-NULL, we query against the in-flight
+data within the appropriate uncommitted transaction.
+
+IMPLEMENTATION NOTES:
+
+The minimal set of type definitions, prototypes, and macros needed
+for implementing a DLZ driver is in ../modules/dlz_minimal.h.  Copy this
+header file into your source tree when creating an external DLZ module.
+
+The DLZ dlopen driver provides a set of callback functions:
+
+  - void log(int level, const char *fmt, ...);
+
+    Writes the specified string to the named log, at the specified
+    log level.  Uses printf() format semantics.
+
+  - isc_result_t putrr(dns_sdlzlookup_t *lookup, const char *type,
+                       dns_ttl_t ttl, const char *data);
+
+    Puts a DNS resource record into the query response, which
+    referenced by the opaque structure 'lookup' provided by named.
+
+  - isc_result_t putnamedrr(dns_sdlzallnotes_t *allnodes,
+                            const char *name, const char *type,
+                            dns_ttl_t ttl, const char *data);
+
+    Puts a DNS resource record into an AXFR response, which is
+    referenced by the opaque structure 'allnodes' provided by named.
+
+  - isc_result_t writeable_zone(dns_view_t *view, const char *zone_name);
+
+    Allows the DLZ module to inform named that a given zone can receive
+    DDNS updates.  (Note: This is not currently supported for DLZ
+    databases that are configured as 'search no;')
+
+The external DLZ module can define the following functions (some of these
+are mandatory, others optional).
+
+  - int dlz_version(unsigned int *flags);
+
+    Required for alL external DLZ modules, to indicate the version number
+    of the DLZ dlopen driver that this module supports.  It should return
+    the value DLZ_DLOPEN_VERSION, which is defined in the file
+    contrib/dlz/modules/dlz_minimal.h and is currently 3.  'flags' is
+    updated to indicate capabilities of the module.  In particular, if
+    the module is thread-safe then it sets 'flags' to include
+    DNS_SDLZFLAG_THREADSAFE.  (Other capability flags may be added in
+    the future.)
+
+  - isc_result_t dlz_create(const char *dlzname,
+                            unsigned int argc, char *argv[],
+                            void **dbdata, ...);
+
+    Required for all external DLZ modules; this call initializes the
+    module.
+
+  - void dlz_destroy(void *dbdata);
+
+    Optional.  If supplied, this will be called when the driver is
+    unloaded.
+
+  - isc_result_t dlz_findzonedb(void *dbdata, const char *name,
+                                dns_clientinfomethods_t *methods,
+                                dns_clientinfo_t *clientinfo);
+
+    Required for all external DLZ modules.  This indicates whether
+    the DLZ module can answer for the given name.  Returns ISC_R_SUCCESS
+    if so, and ISC_R_NOTFOUND if not.  As an optimization, it can
+    also return ISC_R_NOMORE: this indicates that the DLZ module has
+    no data for the given name or for any name above it in the DNS.
+    This prevents named from searching for a zone cut.
+
+   - isc_result_t dlz_lookup(const char *zone, const char *name, void *dbdata,
+                             dns_sdlzlookup_t *lookup,
+                             dns_clientinfomethods_t *methods,
+                             dns_clientinfo_t *clientinfo);
+
+    Required for all external DLZ modules.  This carries out the database
+    lookup for a query.
+
+  - isc_result_t dlz_allowzonexfr(void *dbdata, const char *name,
+                                  const char *client);
+
+    Optional.  Supply this if you want the module to support AXFR
+    for the specified zone and client.  A return value of ISC_R_SUCCESS
+    means AXFR is allowed, any other value means it isn't.
+
+  -  isc_result_t dlz_allnodes(const char *zone, void *dbdata,
+                               dns_sdlzallnodes_t *allnodes);
+
+     Optional, but must be supplied dlz_allowzonexfr() is.  This function
+     returns all nodes in the zone in order to perform a zone transfer.
+
+  - isc_result_t dlz_newversion(const char *zone, void *dbdata,
+                                void **versionp);
+
+    Optional.  Supply this if you want the module to support DDNS
+    updates.  This function starts a transaction in the database.
+
+
+  - void dlz_closeversion(const char *zone, bool commit,
+                          void *dbdata, void **versionp);
+
+    Optional, but must be supplied if dlz_newversion() is.  This function
+    closes a transaction.  'commit' indicates whether to commit the changes
+    to the database, or ignore them.
+
+  - isc_result_t dlz_configure(dns_view_t *view, void *dbdata);
+
+    Optional, but must be supplied in order to support DDNS updates.
+
+  - bool dlz_ssumatch(const char *signer, const char *name,
+                               const char *tcpaddr, const char *type,
+                               const char *key, uint32_t keydatalen,
+                               uint8_t *keydata, void *dbdata);
+
+    Optional, but must be supplied in order to support DDNS updates.
+
+  - isc_result_t dlz_addrdataset(const char *name, const char *rdatastr,
+                                 void *dbdata, void *version);
+
+    Optional, but must be supplied in order to support DDNS updates.
+    Adds the data in 'rdatastr' to a database node.
+
+  - isc_result_t dlz_subrdataset(const char *name, const char *rdatastr,
+                                 void *dbdata, void *version);
+
+    Optional, but must be supplied in order to support DDNS updates.
+    Removes the data in 'rdatastr' from a database node.
+
+  - isc_result_t dlz_delrdataset(const char *name, const char *rdatastr,
+                                 void *dbdata, void *version);
+
+    Optional, but must be supplied in order to support DDNS updates.
+    Deletes all data matching the type specified in 'rdatastr' from
+    the database.