/contrib/bind9/doc/misc/sdb

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