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