Adding upstream version 1:9.11.5.P4+dfsg.upstream/1%9.11.5.P4+dfsgupstream

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

1 files changed, 167 insertions, 0 deletions

diff --git a/doc/misc/sdb b/doc/misc/sdb
new file mode 100644
index 0000000..d36e79c
--- /dev/null
+++ b/doc/misc/sdb
@@ -0,0 +1,167 @@
+Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+
+See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
+
+Using the BIND 9 Simplified Database Interface
+
+This document describes the care and feeding of the BIND 9 Simplified
+Database Interface, which allows you to extend BIND 9 with new ways
+of obtaining the data that is published as DNS zones.
+
+
+The Original BIND 9 Database Interface
+
+BIND 9 has a well-defined "back-end database interface" that makes it
+possible to replace the component of the name server responsible for
+the storage and retrieval of zone data, called the "database", on a
+per-zone basis.  The default database is an in-memory, red-black-tree
+data structure commonly referred to as "rbtdb", but it is possible to
+write drivers to support any number of alternative database
+technologies such as in-memory hash tables, application specific
+persistent on-disk databases, object databases, or relational
+databases.
+
+The original BIND 9 database interface defined in <dns/db.h> is
+designed to efficiently support the full set of database functionality
+needed by a name server that implements the complete DNS protocols,
+including features such as zone transfers, dynamic update, and DNSSEC.
+Each of these aspects of name server operations places its own set of
+demands on the data store, with the result that the database API is
+quite complex and contains operations that are highly specific to the
+DNS.  For example, data are stored in a binary format, the name space
+is tree structured, and sets of data records are conceptually
+associated with DNSSEC signature sets.  For these reasons, writing a
+driver using this interface is a highly nontrivial undertaking.
+
+
+The Simplified Database Interface
+
+Many BIND users wish to provide access to various data sources through
+the DNS, but are not necessarily interested in completely replacing
+the in-memory "rbt" database or in supporting features like dynamic
+update, DNSSEC, or even zone transfers.
+
+Often, all you want is limited, read-only DNS access to an existing
+system.  For example, you may have an existing relational database
+containing hostname/address mappings and wish to provide forvard and
+reverse DNS lookups based on this information.  Or perhaps you want to
+set up a simple DNS-based load balancing system where the name server
+answers queries about a single DNS name with a dynamically changing
+set of A records.
+
+BIND 9.1 introduced a new, simplified database interface, or "sdb",
+which greatly simplifies the writing of drivers for these kinds of
+applications.
+
+
+The sdb Driver
+
+An sdb driver is an object module, typically written in C, which is
+linked into the name server and registers itself with the sdb
+subsystem.  It provides a set of callback functions, which also serve
+to advertise its capabilities.  When the name server receives DNS
+queries, invokes the callback functions to obtain the data to respond
+with.
+
+Unlike the full database interface, the sdb interface represents all
+domain names and resource records as ASCII text.
+
+
+Writing an sdb Driver
+
+When a driver is registered, it specifies its name, a list of callback
+functions, and flags.
+
+The flags specify whether the driver wants to use relative domain
+names where possible.
+
+The callback functions are as follows.  The only one that must be
+defined is lookup().
+
+  - create(zone, argc, argv, driverdata, dbdata)
+	  Create a database object for "zone".
+
+  - destroy(zone, driverdata, dbdata)
+	  Destroy the database object for "zone".
+
+  - lookup(zone, name, dbdata, lookup)
+	  Return all the records at the domain name "name".
+
+  - authority(zone, dbdata, lookup)
+	  Return the SOA and NS records at the zone apex.
+
+  - allnodes(zone, dbdata, allnodes)
+	  Return all data in the zone, for zone transfers.
+
+For more detail about these functions and their parameters, see
+bind9/lib/dns/include/dns/sdb.h.  For example drivers, see
+bind9/contrib/sdb.
+
+
+Rebuilding the Server
+
+The driver module and header file must be copied to (or linked into)
+the bind9/bin/named and bind9/bin/named/include directories
+respectively, and must be added to the DBDRIVER_OBJS and DBDRIVER_SRCS
+lines in bin/named/Makefile.in (e.g. for the timedb sample sdb driver,
+add timedb.c to DBDRIVER_SRCS and timedb.@O@ to DBDRIVER_OBJS).  If
+the driver needs additional header files or libraries in nonstandard
+places, the DBDRIVER_INCLUDES and DBDRIVER_LIBS lines should also be
+updated.
+
+Calls to dns_sdb_register() and dns_sdb_unregister() (or wrappers,
+e.g. timedb_init() and timedb_clear() for the timedb sample sdb
+driver) must be inserted into the server, in bind9/bin/named/main.c.
+Registration should be in setup(), before the call to
+ns_server_create().  Unregistration should be in cleanup(),
+after the call to ns_server_destroy().  A #include should be added
+corresponding to the driver header file.
+
+You should try doing this with one or more of the sample drivers
+before attempting to write a driver of your own.
+
+
+Configuring the Server
+
+To make a zone use a new database driver, specify a "database" option
+in its "zone" statement in named.conf.  For example, if the driver
+registers itself under the name "acmedb", you might say
+
+   zone "foo.com" {
+	   database "acmedb";
+   };
+
+You can pass arbitrary arguments to the create() function of the
+driver by adding any number of whitespace-separated words after the
+driver name:
+
+   zone "foo.com" {
+	   database "acmedb -mode sql -connect 10.0.0.1";
+   };
+
+
+Hints for Driver Writers
+
+ - If a driver is generating data on the fly, it probably should
+   not implement the allnodes() function, since a zone transfer
+   will not be meaningful.  The allnodes() function is more relevant
+   with data from a database.
+
+ - The authority() function is necessary if and only if the lookup()
+   function will not add SOA and NS records at the zone apex.  If
+   SOA and NS records are provided by the lookup() function,
+   the authority() function should be NULL.
+
+ - When a driver is registered, an opaque object can be provided.  This
+   object is passed into the database create() and destroy() functions.
+
+ - When a database is created, an opaque object can be created that
+   is associated with that database.  This object is passed into the
+   lookup(), authority(), and allnodes() functions, and is
+   destroyed by the destroy() function.
+
+
+Future Directions
+
+A future release may support dynamic loading of sdb drivers.
+