0N/ACopyright (C) 2000, 2001 Internet Software Consortium.
0N/AUsing the BIND 9 Simplified Database Interface
0N/AThis document describes the care and feeding of the BIND 9 Simplified
0N/ADatabase Interface, which allows you to extend BIND 9 with new ways
0N/Aof obtaining the data that is published as DNS zones.
0N/AThe Original BIND 9 Database Interface
0N/ABIND 9 has a well-defined "back-end database interface" that makes it
0N/Apossible to replace the component of the name server responsible for
0N/Athe storage and retrieval of zone data, called the "database", on a
0N/Aper-zone basis. The default database is an in-memory, red-black-tree
0N/Adata structure commonly referred to as "rbtdb", but it is possible to
0N/Awrite drivers to support any number of alternative database
2362N/Atechnologies such as in-memory hash tables, application specific
2362N/Apersistent on-disk databases, object databases, or relational
0N/AThe original BIND 9 database interface defined in <
dns/db.h> is
0N/Adesigned to efficiently support the full set of database functionality
0N/Aneeded by a name server that implements the complete DNS protocols,
0N/Aincluding features such as zone transfers, dynamic update, and DNSSEC.
0N/AEach of these aspects of name server operations places its own set of
0N/Ademands on the data store, with the result that the database API is
0N/Aquite complex and contains operations that are highly specific to the
0N/ADNS. For example, data are stored in a binary format, the name space
0N/Ais tree structured, and sets of data records are conceptually
0N/Aassociated with DNSSEC signature sets. For these reasons, writing a
0N/Adriver using this interface is a highly nontrivial undertaking.
0N/AThe Simplified Database Interface
0N/AMany BIND users wish to provide access to various data sources through
0N/Athe DNS, but are not necessarily interested in completely replacing
0N/Athe in-memory "rbt" database or in supporting features like dynamic
0N/Aupdate, DNSSEC, or even zone transfers.
0N/AOften, all you want is limited, read-only DNS access to an existing
0N/Asystem. For example, you may have an existing relational database
2475N/Areverse DNS lookups based on this information. Or perhaps you want to
2475N/Aset up a simple DNS-based load balancing system where the name server
0N/Aanswers queries about a single DNS name with a dynamically changing
0N/ABIND 9.1 introduces a new, simplified database interface, or "sdb",
0N/Awhich greatly simplifies the writing of drivers for these kinds of
0N/AAn sdb driver is an object module, typically written in C, which is
0N/Alinked into the name server and registers itself with the sdb
0N/Asubsystem. It provides a set of callback functions, which also serve
0N/Ato advertise its capabilities. When the name server receives DNS
0N/Aqueries, invokes the callback functions to obtain the data to respond
0N/AUnlike the full database interface, the sdb interface represents all
0N/Adomain names and resource records as ASCII text.
0N/AWriting an sdb Driver
0N/AWhen a driver is registered, it specifies its name, a list of callback
0N/Afunctions, and flags.
2475N/AThe flags specify whether the driver wants to use relative domain
0N/AThe callback functions are as follows. The only one that must be
0N/A - create(zone, argc, argv, driverdata, dbdata)
0N/A Create a database object for "zone".
0N/A - destroy(zone, driverdata, dbdata)
0N/A Destroy the database object for "zone".
0N/A - lookup(zone, name, dbdata, lookup)
0N/A Return all the records at the domain name "name".
0N/A - authority(zone, dbdata, lookup)
0N/A Return the SOA and NS records at the zone apex.
0N/A - allnodes(zone, dbdata, allnodes)
0N/A Return all data in the zone, for zone transfers.
0N/AFor more detail about these functions and their parameters, see
0N/ARebuilding the Server
0N/AThe driver module and header file must be copied to (or linked into)
0N/Arespectively, and must be added to the DBDRIVER_OBJS and DBDRIVER_SRCS
0N/Aadd
timedb.c to DBDRIVER_SRCS and timedb.@O@ to DBDRIVER_OBJS). If
0N/Athe driver needs additional header files or libraries in nonstandard
0N/Aplaces, the DBDRIVER_INCLUDES and DBDRIVER_LIBS lines should also be
0N/ACalls to dns_sdb_register() and dns_sdb_unregister() (or wrappers,
0N/Ae.g. timedb_init() and timedb_clear() for the timedb sample sdb
0N/ARegistration should be in setup(), before the call to
0N/Ans_server_create(). Unregistration should be in cleanup(),
0N/Aafter the call to ns_server_destroy(). A #include should be added
0N/Acorresponding to the driver header file.
0N/AYou should try doing this with one or more of the sample drivers
0N/Abefore attempting to write a driver of your own.
0N/ATo make a zone use a new database driver, specify a "database" option
2475N/Aregisters itself under the name "acmedb", you might say
2475N/AYou can pass arbitrary arguments to the create() function of the
0N/Adriver by adding any number of whitespace-separated words after the
0N/A database "acmedb -mode sql -connect 10.0.0.1";
0N/AHints for Driver Writers
0N/A - If a driver is generating data on the fly, it probably should
0N/A not implement the allnodes() function, since a zone transfer
0N/A will not be meaningful. The allnodes() function is more relevant
0N/A with data from a database.
0N/A - The authority() function is necessary if and only if the lookup()
0N/A function will not add SOA and NS records at the zone apex. If
0N/A SOA and NS records are provided by the lookup() function,
0N/A the authority() function should be NULL.
0N/A - When a driver is registered, an opaque object can be provided. This
0N/A object is passed into the database create() and destroy() functions.
0N/A - When a database is created, an opaque object can be created that
0N/A is associated with that database. This object is passed into the
0N/A lookup(), authority(), and allnodes() functions, and is
0N/A destroyed by the destroy() function.
A future release may support dynamic loading of sdb drivers.
$Id: sdb,v 1.4 2001/01/09 21:50:30 bwelling Exp $