sdb revision 705cc52bbf49bdeedbaf255e91af2e325fc79ba5
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekCopyright (C) 2000, 2001 Internet Software Consortium.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekSee COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekUsing the BIND 9 Simplified Database Interface
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekThis document describes the care and feeding of the BIND 9 Simplified
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekDatabase Interface, which allows you to extend BIND 9 with new ways
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekof obtaining the data that is published as DNS zones.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekThe Original BIND 9 Database Interface
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekBIND 9 has a well-defined "back-end database interface" that makes it
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekpossible to replace the component of the name server responsible for
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekthe storage and retrieval of zone data, called the "database", on a
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekper-zone basis. The default database is an in-memory, red-black-tree
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekdata structure commonly referred to as "rbtdb", but it is possible to
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekwrite drivers to support any number of alternative database
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozektechnologies such as in-memory hash tables, application specific
13857cf3d073b697cd037788ceabde7eb41a22c0Jan Zelenypersistent on-disk databases, object databases, or relational
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekThe original BIND 9 database interface defined in <dns/db.h> is
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekdesigned to efficiently support the full set of database functionality
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekneeded by a name server that implements the complete DNS protocols,
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekincluding features such as zone transfers, dynamic update, and DNSSEC.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekEach of these aspects of name server operations places its own set of
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekdemands on the data store, with the result that the database API is
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekquite complex and contains operations that are highly specific to the
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekDNS. For example, data are stored in a binary format, the name space
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekis tree structured, and sets of data records are conceptually
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekassociated with DNSSEC signature sets. For these reasons, writing a
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekdriver using this interface is a highly nontrivial undertaking.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekThe Simplified Database Interface
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekMany BIND users wish to provide access to various data sources through
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekthe DNS, but are not necessarily interested in completely replacing
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekthe in-memory "rbt" database or in supporting features like dynamic
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekupdate, DNSSEC, or even zone transfers.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekOften, all you want is limited, read-only DNS access to an existing
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozeksystem. For example, you may have an existing relational database
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekcontaining hostname/address mappings and wish to provide forvard and
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekreverse DNS lookups based on this information. Or perhaps you want to
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekset up a simple DNS-based load balancing system where the name server
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekanswers queries about a single DNS name with a dynamically changing
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekset of A records.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekBIND 9.1 introduced a new, simplified database interface, or "sdb",
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekwhich greatly simplifies the writing of drivers for these kinds of
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekapplications.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekThe sdb Driver
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekAn sdb driver is an object module, typically written in C, which is
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozeklinked into the name server and registers itself with the sdb
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozeksubsystem. It provides a set of callback functions, which also serve
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekto advertise its capabilities. When the name server receives DNS
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekqueries, invokes the callback functions to obtain the data to respond
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekUnlike the full database interface, the sdb interface represents all
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekdomain names and resource records as ASCII text.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekWriting an sdb Driver
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekWhen a driver is registered, it specifies its name, a list of callback
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekfunctions, and flags.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekThe flags specify whether the driver wants to use relative domain
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozeknames where possible.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekThe callback functions are as follows. The only one that must be
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekdefined is lookup().
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek - create(zone, argc, argv, driverdata, dbdata)
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek Create a database object for "zone".
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek - destroy(zone, driverdata, dbdata)
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek Destroy the database object for "zone".
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek - lookup(zone, name, dbdata, lookup)
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek Return all the records at the domain name "name".
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek - authority(zone, dbdata, lookup)
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek Return the SOA and NS records at the zone apex.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek - allnodes(zone, dbdata, allnodes)
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek Return all data in the zone, for zone transfers.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekFor more detail about these functions and their parameters, see
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekbind9/lib/dns/include/dns/sdb.h. For example drivers, see
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekRebuilding the Server
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekThe driver module and header file must be copied to (or linked into)
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekthe bind9/bin/named and bind9/bin/named/include directories
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekrespectively, and must be added to the DBDRIVER_OBJS and DBDRIVER_SRCS
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozeklines in bin/named/Makefile.in (e.g. for the timedb sample sdb driver,
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekadd timedb.c to DBDRIVER_SRCS and timedb.@O@ to DBDRIVER_OBJS). If
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekthe driver needs additional header files or libraries in nonstandard
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozekplaces, the DBDRIVER_INCLUDES and DBDRIVER_LIBS lines should also be
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekCalls to dns_sdb_register() and dns_sdb_unregister() (or wrappers,
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozeke.g. timedb_init() and timedb_clear() for the timedb sample sdb
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit Bosedriver) must be inserted into the server, in bind9/bin/named/main.c.
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit BoseRegistration should be in setup(), before the call to
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit Bosens_server_create(). Unregistration should be in cleanup(),
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit Boseafter the call to ns_server_destroy(). A #include should be added
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit Bosecorresponding to the driver header file.
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit BoseYou should try doing this with one or more of the sample drivers
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit Bosebefore attempting to write a driver of your own.
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit BoseConfiguring the Server
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit BoseTo make a zone use a new database driver, specify a "database" option
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit Bosein its "zone" statement in named.conf. For example, if the driver
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit Boseregisters itself under the name "acmedb", you might say
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit Bose database "acmedb";
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit BoseYou can pass arbitrary arguments to the create() function of the
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit Bosedriver by adding any number of whitespace-separated words after the
44ca4ec72b85c875b91842084834c25b144adf0cSumit Bose database "acmedb -mode sql -connect 10.0.0.1";
948c021d50ce26e5935f4909ef7d4c61d28b02b5Sumit BoseHints for Driver Writers
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek - If a driver is generating data on the fly, it probably should
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek not implement the allnodes() function, since a zone transfer
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek will not be meaningful. The allnodes() function is more relevant
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek with data from a database.
44ca4ec72b85c875b91842084834c25b144adf0cSumit Bose - The authority() function is necessary if and only if the lookup()
44ca4ec72b85c875b91842084834c25b144adf0cSumit Bose function will not add SOA and NS records at the zone apex. If
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek SOA and NS records are provided by the lookup() function,
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek the authority() function should be NULL.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek - When a driver is registered, an opaque object can be provided. This
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek object is passed into the database create() and destroy() functions.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek - When a database is created, an opaque object can be created that
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek is associated with that database. This object is passed into the
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek lookup(), authority(), and allnodes() functions, and is
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek destroyed by the destroy() function.
44ca4ec72b85c875b91842084834c25b144adf0cSumit BoseFuture Directions
6f51c802311fd81a409a26763ed45b28a3234d0dJakub HrozekA future release may support dynamic loading of sdb drivers.
6f51c802311fd81a409a26763ed45b28a3234d0dJakub Hrozek$Id: sdb,v 1.5 2001/05/30 23:02:03 bwelling Exp $