"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.12.3-P1/doc/misc/sdb" (7 Dec 2018, 6444 Bytes) of package /linux/misc/dns/bind9/9.12.3-P1/bind-9.12.3-P1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    2 
    3 See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
    4 
    5 Using the BIND 9 Simplified Database Interface
    6 
    7 This document describes the care and feeding of the BIND 9 Simplified
    8 Database Interface, which allows you to extend BIND 9 with new ways
    9 of obtaining the data that is published as DNS zones.
   10 
   11 
   12 The Original BIND 9 Database Interface
   13 
   14 BIND 9 has a well-defined "back-end database interface" that makes it
   15 possible to replace the component of the name server responsible for
   16 the storage and retrieval of zone data, called the "database", on a
   17 per-zone basis.  The default database is an in-memory, red-black-tree
   18 data structure commonly referred to as "rbtdb", but it is possible to
   19 write drivers to support any number of alternative database
   20 technologies such as in-memory hash tables, application specific
   21 persistent on-disk databases, object databases, or relational
   22 databases.
   23 
   24 The original BIND 9 database interface defined in <dns/db.h> is
   25 designed to efficiently support the full set of database functionality
   26 needed by a name server that implements the complete DNS protocols,
   27 including features such as zone transfers, dynamic update, and DNSSEC.
   28 Each of these aspects of name server operations places its own set of
   29 demands on the data store, with the result that the database API is
   30 quite complex and contains operations that are highly specific to the
   31 DNS.  For example, data are stored in a binary format, the name space
   32 is tree structured, and sets of data records are conceptually
   33 associated with DNSSEC signature sets.  For these reasons, writing a
   34 driver using this interface is a highly nontrivial undertaking.
   35 
   36 
   37 The Simplified Database Interface
   38 
   39 Many BIND users wish to provide access to various data sources through
   40 the DNS, but are not necessarily interested in completely replacing
   41 the in-memory "rbt" database or in supporting features like dynamic
   42 update, DNSSEC, or even zone transfers.
   43 
   44 Often, all you want is limited, read-only DNS access to an existing
   45 system.  For example, you may have an existing relational database
   46 containing hostname/address mappings and wish to provide forvard and
   47 reverse DNS lookups based on this information.  Or perhaps you want to
   48 set up a simple DNS-based load balancing system where the name server
   49 answers queries about a single DNS name with a dynamically changing
   50 set of A records.
   51 
   52 BIND 9.1 introduced a new, simplified database interface, or "sdb",
   53 which greatly simplifies the writing of drivers for these kinds of
   54 applications.
   55 
   56 
   57 The sdb Driver
   58 
   59 An sdb driver is an object module, typically written in C, which is
   60 linked into the name server and registers itself with the sdb
   61 subsystem.  It provides a set of callback functions, which also serve
   62 to advertise its capabilities.  When the name server receives DNS
   63 queries, invokes the callback functions to obtain the data to respond
   64 with.
   65 
   66 Unlike the full database interface, the sdb interface represents all
   67 domain names and resource records as ASCII text.
   68 
   69 
   70 Writing an sdb Driver
   71 
   72 When a driver is registered, it specifies its name, a list of callback
   73 functions, and flags.
   74 
   75 The flags specify whether the driver wants to use relative domain
   76 names where possible.
   77 
   78 The callback functions are as follows.  The only one that must be
   79 defined is lookup().
   80 
   81   - create(zone, argc, argv, driverdata, dbdata)
   82 	  Create a database object for "zone".
   83 
   84   - destroy(zone, driverdata, dbdata)
   85 	  Destroy the database object for "zone".
   86 
   87   - lookup(zone, name, dbdata, lookup)
   88 	  Return all the records at the domain name "name".
   89 
   90   - authority(zone, dbdata, lookup)
   91 	  Return the SOA and NS records at the zone apex.
   92 
   93   - allnodes(zone, dbdata, allnodes)
   94 	  Return all data in the zone, for zone transfers.
   95 
   96 For more detail about these functions and their parameters, see
   97 bind9/lib/dns/include/dns/sdb.h.  For example drivers, see
   98 bind9/contrib/sdb.
   99 
  100 
  101 Rebuilding the Server
  102 
  103 The driver module and header file must be copied to (or linked into)
  104 the bind9/bin/named and bind9/bin/named/include directories
  105 respectively, and must be added to the DBDRIVER_OBJS and DBDRIVER_SRCS
  106 lines in bin/named/Makefile.in (e.g. for the timedb sample sdb driver,
  107 add timedb.c to DBDRIVER_SRCS and timedb.@O@ to DBDRIVER_OBJS).  If
  108 the driver needs additional header files or libraries in nonstandard
  109 places, the DBDRIVER_INCLUDES and DBDRIVER_LIBS lines should also be
  110 updated.
  111 
  112 Calls to dns_sdb_register() and dns_sdb_unregister() (or wrappers,
  113 e.g. timedb_init() and timedb_clear() for the timedb sample sdb
  114 driver) must be inserted into the server, in bind9/bin/named/main.c.
  115 Registration should be in setup(), before the call to
  116 named_server_create().  Unregistration should be in cleanup(),
  117 after the call to ns_server_destroy().  A #include should be added
  118 corresponding to the driver header file.
  119 
  120 You should try doing this with one or more of the sample drivers
  121 before attempting to write a driver of your own.
  122 
  123 
  124 Configuring the Server
  125 
  126 To make a zone use a new database driver, specify a "database" option
  127 in its "zone" statement in named.conf.  For example, if the driver
  128 registers itself under the name "acmedb", you might say
  129 
  130    zone "foo.com" {
  131 	   database "acmedb";
  132    };
  133 
  134 You can pass arbitrary arguments to the create() function of the
  135 driver by adding any number of whitespace-separated words after the
  136 driver name:
  137 
  138    zone "foo.com" {
  139 	   database "acmedb -mode sql -connect 10.0.0.1";
  140    };
  141 
  142 
  143 Hints for Driver Writers
  144 
  145  - If a driver is generating data on the fly, it probably should
  146    not implement the allnodes() function, since a zone transfer
  147    will not be meaningful.  The allnodes() function is more relevant
  148    with data from a database.
  149 
  150  - The authority() function is necessary if and only if the lookup()
  151    function will not add SOA and NS records at the zone apex.  If
  152    SOA and NS records are provided by the lookup() function,
  153    the authority() function should be NULL.
  154 
  155  - When a driver is registered, an opaque object can be provided.  This
  156    object is passed into the database create() and destroy() functions.
  157 
  158  - When a database is created, an opaque object can be created that
  159    is associated with that database.  This object is passed into the
  160    lookup(), authority(), and allnodes() functions, and is
  161    destroyed by the destroy() function.
  162 
  163 
  164 Future Directions
  165 
  166 A future release may support dynamic loading of sdb drivers.
  167