sdb revision 5f439956720839197eb984c397f90bdce40fa263
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsCopyright (C) 2000 Internet Software Consortium.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsSee COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsUsing the BIND 9 Simplified Database Interface
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsThis document describes the care and feeding of the BIND 9 Simplified
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsDatabase Interface, which allows you to extend BIND 9 with new ways
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsof obtaining the data that is published as DNS zones.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsThe Original BIND 9 Database Interface
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsBIND 9 has a well-defined "back-end database interface" that makes it
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewspossible to replace the component of the name server responsible for
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsthe storage and retrieval of zone data, called the "database", on a
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsper-zone basis. The default database is an in-memory, red-black-tree
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsdata structure commonly referred to as "rbtdb", but it is possible to
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewswrite drivers to support any number of alternative database
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewstechnologies such as in-memory hash tables, application specific
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewspersistent on-disk databases, object databases, or relational
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsThe original BIND 9 database interface defined in <dns/db.h> is
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsdesigned to efficiently support the full set of database functionality
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsneeded by a name server that implements the complete DNS protocols,
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsincluding features such as zone transfers, dynamic update, and DNSSEC.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsEach of these aspects of name server operations places its own set of
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsdemands on the data store, with the result that the database API is
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsquite complex and contains operations that are highly specific to the
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsDNS. For example, data are stored in a binary format, the name space
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsis tree structured, and sets of data records are conceptually
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsassociated with DNSSEC signature sets. For these reasons, writing a
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsdriver using this interface is a highly nontrivial undertaking.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsThe Simplified Database Interface
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsMany BIND users wish to provide access to various data sources through
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsthe DNS, but are not necessarily interested in completely replacing
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsthe in-memory "rbt" database or in supporting features like dynamic
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsupdate, DNSSEC, or even zone transfers.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsOften, all you want is limited, read-only DNS access to an existing
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewssystem. For example, you may have an existing relational database
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewscontaining hostname/address mappings and wish to provide forvard and
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsreverse DNS lookups based on this information. Or perhaps you want to
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsset up a simple DNS-based load balancing system where the name server
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsanswers queries about a single DNS name with a dynamically changing
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsset of A records.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsBIND 9.1 introduces a new, simplified database interface, or "sdb",
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewswhich greatly simplifies the writing of drivers for these kinds of
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsapplications.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsThe sdb Driver
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsAn sdb driver is an object module, typically written in C, which is
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewslinked into the name server and registers itself with the sdb
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewssubsystem. It provides a set of callback functions, which also serve
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsto advertise its capabilities. When the name server receives DNS
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsqueries, invokes the callback functions to obtain the data to respond
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsUnlike the full database interface, the sdb interface represents all
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsdomain names and resource records as ASCII text.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsWriting an sdb Driver
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsWhen a driver is registered, it specifies its name, a list of callback
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsfunctions, and flags.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsThe flags specify whether the driver wants to use relative domain
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsnames where possible.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsThe callback functions are as follows. The only one that must be
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsdefined is lookup().
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews - create(zone, argc, argv, driverdata, dbdata)
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews Create a database object for "zone".
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews - destroy(zone, driverdata, dbdata)
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews Destroy the database object for "zone".
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews - lookup(zone, name, dbdata, lookup)
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews Return all the records at the domain name "name".
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews - authority(zone, dbdata, lookup)
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews Return the SOA and NS records at the zone apex.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews - allnodes(zone, dbdata, allnodes)
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews Return all data in the zone, for zone transfers.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsFor more detail about these functions and their parameters, see
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsbind9/lib/dns/include/dns/sdb.h. For example drivers, see
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsRebuilding the Server
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsThe driver module and header file must be copied to (or linked into)
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsthe bind9/bin/named and bind9/bin/named/include directories
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsrespectively, and must be added to the DBDRIVER_OBJS and DBDRIVER_SRCS
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewslines in bin/named/Makefile.in (e.g. for the timedb sample sdb driver,
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsadd timedb.c to DBDRIVER_SRCS and timedb.@O@ to DBDRIVER_OBJS). If
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsthe driver needs additional header files or libraries in nonstandard
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsplaces, the DBDRIVER_INCLUDES and DBDRIVER_LIBS lines should also be
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsCalls to dns_sdb_register() and dns_sdb_unregister() (or wrappers,
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewse.g. timedb_init() and timedb_clear() for the timedb sample sdb
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsdriver) must be inserted into the server, in bind9/bin/named/main.c.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsRegistration should be in setup(), before the call to
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsns_server_create(). Unregistration should be in cleanup(),
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsafter the call to ns_server_destroy(). A #include should be added
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewscorresponding to the driver header file.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsYou should try doing this with one or more of the sample drivers
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsbefore attempting to write a driver of your own.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsConfiguring the Server
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsTo make a zone use a new database driver, specify a "database" option
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsin its "zone" statement in named.conf. For example, if the driver
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsregisters itself under the name "acmedb", you might say
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews database "acmedb";
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsYou can pass arbitrary arguments to the create() function of the
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrewsdriver by adding any number of whitespace-separated words after the
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews database "acmedb -mode sql -connect 10.0.0.1";
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsHints for Driver Writers
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews - If a driver is generating data on the fly, it probably should
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews not implement the allnodes() function, since a zone transfer
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews will not be meaningful. The allnodes() function is more relevant
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews with data from a database.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews - The authority() function is necessary if and only if the lookup()
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews function will not add SOA and NS records at the zone apex. If
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews SOA and NS records are provided by the lookup() function,
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews the authority() function should be NULL.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews - When a driver is registered, an opaque object can be provided. This
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews object is passed into the database create() and destroy() functions.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews - When a database is created, an opaque object can be created that
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews is associated with that database. This object is passed into the
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews lookup(), authority(), and allnodes() functions, and is
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews destroyed by the destroy() function.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsFuture Directions
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark AndrewsA future release may support dynamic loading of sdb drivers.
582f8b9a8d170a80ef67475bddb8ad5cf7cd7cadMark Andrews$Id: sdb,v 1.3 2000/11/30 02:03:18 sjacob Exp $