sdb revision 0c27b3fe77ac1d5094ba3521e8142d9e7973133f
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossCopyright (C) 2000, 2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossThis Source Code Form is subject to the terms of the Mozilla Public
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossLicense, v. 2.0. If a copy of the MPL was not distributed with this
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossfile, You can obtain one at http://mozilla.org/MPL/2.0/.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossUsing the BIND 9 Simplified Database Interface
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossThis document describes the care and feeding of the BIND 9 Simplified
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossDatabase Interface, which allows you to extend BIND 9 with new ways
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossof obtaining the data that is published as DNS zones.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossThe Original BIND 9 Database Interface
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossBIND 9 has a well-defined "back-end database interface" that makes it
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosspossible to replace the component of the name server responsible for
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossthe storage and retrieval of zone data, called the "database", on a
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossper-zone basis. The default database is an in-memory, red-black-tree
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossdata structure commonly referred to as "rbtdb", but it is possible to
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosswrite drivers to support any number of alternative database
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosstechnologies such as in-memory hash tables, application specific
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosspersistent on-disk databases, object databases, or relational
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossThe original BIND 9 database interface defined in <dns/db.h> is
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossdesigned to efficiently support the full set of database functionality
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossneeded by a name server that implements the complete DNS protocols,
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossincluding features such as zone transfers, dynamic update, and DNSSEC.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossEach of these aspects of name server operations places its own set of
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossdemands on the data store, with the result that the database API is
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossquite complex and contains operations that are highly specific to the
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossDNS. For example, data are stored in a binary format, the name space
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossis tree structured, and sets of data records are conceptually
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossassociated with DNSSEC signature sets. For these reasons, writing a
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossdriver using this interface is a highly nontrivial undertaking.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossThe Simplified Database Interface
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossMany BIND users wish to provide access to various data sources through
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossthe DNS, but are not necessarily interested in completely replacing
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossthe in-memory "rbt" database or in supporting features like dynamic
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossupdate, DNSSEC, or even zone transfers.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossOften, all you want is limited, read-only DNS access to an existing
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosssystem. For example, you may have an existing relational database
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosscontaining hostname/address mappings and wish to provide forvard and
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossreverse DNS lookups based on this information. Or perhaps you want to
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossset up a simple DNS-based load balancing system where the name server
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossanswers queries about a single DNS name with a dynamically changing
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossset of A records.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossBIND 9.1 introduced a new, simplified database interface, or "sdb",
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosswhich greatly simplifies the writing of drivers for these kinds of
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossapplications.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossThe sdb Driver
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossAn sdb driver is an object module, typically written in C, which is
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosslinked into the name server and registers itself with the sdb
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosssubsystem. It provides a set of callback functions, which also serve
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossto advertise its capabilities. When the name server receives DNS
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossqueries, invokes the callback functions to obtain the data to respond
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossUnlike the full database interface, the sdb interface represents all
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossdomain names and resource records as ASCII text.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossWriting an sdb Driver
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossWhen a driver is registered, it specifies its name, a list of callback
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossfunctions, and flags.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossThe flags specify whether the driver wants to use relative domain
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossnames where possible.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossThe callback functions are as follows. The only one that must be
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossdefined is lookup().
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross - create(zone, argc, argv, driverdata, dbdata)
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross Create a database object for "zone".
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross - destroy(zone, driverdata, dbdata)
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross Destroy the database object for "zone".
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross - lookup(zone, name, dbdata, lookup)
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross Return all the records at the domain name "name".
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross - authority(zone, dbdata, lookup)
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross Return the SOA and NS records at the zone apex.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross - allnodes(zone, dbdata, allnodes)
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross Return all data in the zone, for zone transfers.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossFor more detail about these functions and their parameters, see
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossbind9/lib/dns/include/dns/sdb.h. For example drivers, see
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossRebuilding the Server
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossThe driver module and header file must be copied to (or linked into)
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossthe bind9/bin/named and bind9/bin/named/include directories
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossrespectively, and must be added to the DBDRIVER_OBJS and DBDRIVER_SRCS
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosslines in bin/named/Makefile.in (e.g. for the timedb sample sdb driver,
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossadd timedb.c to DBDRIVER_SRCS and timedb.@O@ to DBDRIVER_OBJS). If
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossthe driver needs additional header files or libraries in nonstandard
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossplaces, the DBDRIVER_INCLUDES and DBDRIVER_LIBS lines should also be
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossCalls to dns_sdb_register() and dns_sdb_unregister() (or wrappers,
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosse.g. timedb_init() and timedb_clear() for the timedb sample sdb
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossdriver) must be inserted into the server, in bind9/bin/named/main.c.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossRegistration should be in setup(), before the call to
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossns_server_create(). Unregistration should be in cleanup(),
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossafter the call to ns_server_destroy(). A #include should be added
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rosscorresponding to the driver header file.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossYou should try doing this with one or more of the sample drivers
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossbefore attempting to write a driver of your own.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossConfiguring the Server
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossTo make a zone use a new database driver, specify a "database" option
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossin its "zone" statement in named.conf. For example, if the driver
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossregisters itself under the name "acmedb", you might say
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross database "acmedb";
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossYou can pass arbitrary arguments to the create() function of the
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Rossdriver by adding any number of whitespace-separated words after the
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross database "acmedb -mode sql -connect 10.0.0.1";
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon RossHints for Driver Writers
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross - If a driver is generating data on the fly, it probably should
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross not implement the allnodes() function, since a zone transfer
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross will not be meaningful. The allnodes() function is more relevant
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross with data from a database.
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross - The authority() function is necessary if and only if the lookup()
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross function will not add SOA and NS records at the zone apex. If
b819cea2f73f98c5662230cc9affc8cc84f77fcfGordon Ross SOA and NS records are provided by the lookup() function,