contrib/bind9/doc/misc/sdb

   1 Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 Copyright (C) 2000, 2001  Internet Software Consortium.
   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 ns_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
 168
 169 $Id: sdb,v 1.6 2004/03/05 05:04:54 marka Exp $