0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCopyright (C) 2000, 2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsThis Source Code Form is subject to the terms of the Mozilla Public
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsLicense, v. 2.0. If a copy of the MPL was not distributed with this
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsfile, You can obtain one at http://mozilla.org/MPL/2.0/.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonUsing the BIND 9 Simplified Database Interface
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonThis document describes the care and feeding of the BIND 9 Simplified
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonDatabase Interface, which allows you to extend BIND 9 with new ways
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonof obtaining the data that is published as DNS zones.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonThe Original BIND 9 Database Interface
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonBIND 9 has a well-defined "back-end database interface" that makes it
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonpossible to replace the component of the name server responsible for
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonthe storage and retrieval of zone data, called the "database", on a
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonper-zone basis. The default database is an in-memory, red-black-tree
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssondata structure commonly referred to as "rbtdb", but it is possible to
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonwrite drivers to support any number of alternative database
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssontechnologies such as in-memory hash tables, application specific
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonpersistent on-disk databases, object databases, or relational
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonThe original BIND 9 database interface defined in <dns/db.h> is
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssondesigned to efficiently support the full set of database functionality
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonneeded by a name server that implements the complete DNS protocols,
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonincluding features such as zone transfers, dynamic update, and DNSSEC.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonEach of these aspects of name server operations places its own set of
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssondemands on the data store, with the result that the database API is
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonquite complex and contains operations that are highly specific to the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonDNS. For example, data are stored in a binary format, the name space
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonis tree structured, and sets of data records are conceptually
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonassociated with DNSSEC signature sets. For these reasons, writing a
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssondriver using this interface is a highly nontrivial undertaking.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonThe Simplified Database Interface
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonMany BIND users wish to provide access to various data sources through
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonthe DNS, but are not necessarily interested in completely replacing
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonthe in-memory "rbt" database or in supporting features like dynamic
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonupdate, DNSSEC, or even zone transfers.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonOften, all you want is limited, read-only DNS access to an existing
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonsystem. For example, you may have an existing relational database
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssoncontaining hostname/address mappings and wish to provide forvard and
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonreverse DNS lookups based on this information. Or perhaps you want to
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonset up a simple DNS-based load balancing system where the name server
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonanswers queries about a single DNS name with a dynamically changing
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonset of A records.
705cc52bbf49bdeedbaf255e91af2e325fc79ba5Brian WellingtonBIND 9.1 introduced a new, simplified database interface, or "sdb",
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonwhich greatly simplifies the writing of drivers for these kinds of
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonAn sdb driver is an object module, typically written in C, which is
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonlinked into the name server and registers itself with the sdb
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonsubsystem. It provides a set of callback functions, which also serve
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonto advertise its capabilities. When the name server receives DNS
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonqueries, invokes the callback functions to obtain the data to respond
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonUnlike the full database interface, the sdb interface represents all
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssondomain names and resource records as ASCII text.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonWriting an sdb Driver
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonWhen a driver is registered, it specifies its name, a list of callback
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonfunctions, and flags.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonThe flags specify whether the driver wants to use relative domain
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonnames where possible.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonThe callback functions are as follows. The only one that must be
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssondefined is lookup().
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson - create(zone, argc, argv, driverdata, dbdata)
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson Create a database object for "zone".
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson - destroy(zone, driverdata, dbdata)
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson Destroy the database object for "zone".
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson - lookup(zone, name, dbdata, lookup)
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson Return all the records at the domain name "name".
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson - authority(zone, dbdata, lookup)
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson Return the SOA and NS records at the zone apex.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson - allnodes(zone, dbdata, allnodes)
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson Return all data in the zone, for zone transfers.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonFor more detail about these functions and their parameters, see
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonbind9/lib/dns/include/dns/sdb.h. For example drivers, see
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonRebuilding the Server
5f439956720839197eb984c397f90bdce40fa263Stephen JacobThe driver module and header file must be copied to (or linked into)
5f439956720839197eb984c397f90bdce40fa263Stephen Jacobthe bind9/bin/named and bind9/bin/named/include directories
5f439956720839197eb984c397f90bdce40fa263Stephen Jacobrespectively, and must be added to the DBDRIVER_OBJS and DBDRIVER_SRCS
5f439956720839197eb984c397f90bdce40fa263Stephen Jacoblines in bin/named/Makefile.in (e.g. for the timedb sample sdb driver,
5f439956720839197eb984c397f90bdce40fa263Stephen Jacobadd timedb.c to DBDRIVER_SRCS and timedb.@O@ to DBDRIVER_OBJS). If
5f439956720839197eb984c397f90bdce40fa263Stephen Jacobthe driver needs additional header files or libraries in nonstandard
5f439956720839197eb984c397f90bdce40fa263Stephen Jacobplaces, the DBDRIVER_INCLUDES and DBDRIVER_LIBS lines should also be
5f439956720839197eb984c397f90bdce40fa263Stephen JacobCalls to dns_sdb_register() and dns_sdb_unregister() (or wrappers,
5f439956720839197eb984c397f90bdce40fa263Stephen Jacobe.g. timedb_init() and timedb_clear() for the timedb sample sdb
5f439956720839197eb984c397f90bdce40fa263Stephen Jacobdriver) must be inserted into the server, in bind9/bin/named/main.c.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonRegistration should be in setup(), before the call to
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonns_server_create(). Unregistration should be in cleanup(),
e1f0415f3fc134cfc27757d7b015292bd623d9e4Brian Wellingtonafter the call to ns_server_destroy(). A #include should be added
e1f0415f3fc134cfc27757d7b015292bd623d9e4Brian Wellingtoncorresponding to the driver header file.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonYou should try doing this with one or more of the sample drivers
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonbefore attempting to write a driver of your own.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonConfiguring the Server
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonTo make a zone use a new database driver, specify a "database" option
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonin its "zone" statement in named.conf. For example, if the driver
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssonregisters itself under the name "acmedb", you might say
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson database "acmedb";
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonYou can pass arbitrary arguments to the create() function of the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafssondriver by adding any number of whitespace-separated words after the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson database "acmedb -mode sql -connect 10.0.0.1";
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonHints for Driver Writers
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson - If a driver is generating data on the fly, it probably should
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson not implement the allnodes() function, since a zone transfer
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson will not be meaningful. The allnodes() function is more relevant
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson with data from a database.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson - The authority() function is necessary if and only if the lookup()
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson function will not add SOA and NS records at the zone apex. If
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson SOA and NS records are provided by the lookup() function,
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson the authority() function should be NULL.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson - When a driver is registered, an opaque object can be provided. This
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson object is passed into the database create() and destroy() functions.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson - When a database is created, an opaque object can be created that
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson is associated with that database. This object is passed into the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson lookup(), authority(), and allnodes() functions, and is
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson destroyed by the destroy() function.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonFuture Directions
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonA future release may support dynamic loading of sdb drivers.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews$Id: sdb,v 1.6 2004/03/05 05:04:54 marka Exp $