sdb revision 0c27b3fe77ac1d5094ba3521e8142d9e7973133f
43b4c41fbb07705c9df321221ab9cb9832460407Christian MaederCopyright (C) 2000, 2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian MaederThis Source Code Form is subject to the terms of the Mozilla Public
25cc5fbba63f84b47e389af749f55abbbde71c8cChristian MaederLicense, v. 2.0. If a copy of the MPL was not distributed with this
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederfile, You can obtain one at http://mozilla.org/MPL/2.0/.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederUsing the BIND 9 Simplified Database Interface
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederThis document describes the care and feeding of the BIND 9 Simplified
43b4c41fbb07705c9df321221ab9cb9832460407Christian MaederDatabase Interface, which allows you to extend BIND 9 with new ways
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederof obtaining the data that is published as DNS zones.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederThe Original BIND 9 Database Interface
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederBIND 9 has a well-defined "back-end database interface" that makes it
36f63902db2b3463faa9f59912ad106e2d5aaa24Klaus Luettichpossible to replace the component of the name server responsible for
a737caf82de97c1907027c03e4b4509eb492b4b8Christian Maederthe storage and retrieval of zone data, called the "database", on a
a737caf82de97c1907027c03e4b4509eb492b4b8Christian Maederper-zone basis. The default database is an in-memory, red-black-tree
a737caf82de97c1907027c03e4b4509eb492b4b8Christian Maederdata structure commonly referred to as "rbtdb", but it is possible to
a737caf82de97c1907027c03e4b4509eb492b4b8Christian Maederwrite drivers to support any number of alternative database
a737caf82de97c1907027c03e4b4509eb492b4b8Christian Maedertechnologies such as in-memory hash tables, application specific
a737caf82de97c1907027c03e4b4509eb492b4b8Christian Maederpersistent on-disk databases, object databases, or relational
96646aed2ae087b942ae23f15bbe729a8f7c43d3Christian MaederThe original BIND 9 database interface defined in <dns/db.h> is
01e383014b555bbcf639c0ca60c5810b3eff83c0Christian Maederdesigned to efficiently support the full set of database functionality
3b06e23643a9f65390cb8c1caabe83fa7e87a708Till Mossakowskineeded by a name server that implements the complete DNS protocols,
df29370ae8d8b41587957f6bcdcb43a3f1927e47Christian Maederincluding features such as zone transfers, dynamic update, and DNSSEC.
bd54a9917cd87169b8e40bcc5616c537fed85815Christian MaederEach of these aspects of name server operations places its own set of
bd54a9917cd87169b8e40bcc5616c537fed85815Christian Maederdemands on the data store, with the result that the database API is
ce8b15da31cd181b7e90593cbbca98f47eda29d6Till Mossakowskiquite complex and contains operations that are highly specific to the
e7757995211bd395dc79d26fe017d99375f7d2a6Christian MaederDNS. For example, data are stored in a binary format, the name space
e7757995211bd395dc79d26fe017d99375f7d2a6Christian Maederis tree structured, and sets of data records are conceptually
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maederassociated with DNSSEC signature sets. For these reasons, writing a
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maederdriver using this interface is a highly nontrivial undertaking.
2e2094a642e3775b0d76b890556407941d3a53b6Christian MaederThe Simplified Database Interface
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian MaederMany BIND users wish to provide access to various data sources through
e8db9a65830cf71504e33c6f441a67b4d184a3caChristian Maederthe DNS, but are not necessarily interested in completely replacing
c0c2380bced8159ff0297ece14eba948bd236471Christian Maederthe in-memory "rbt" database or in supporting features like dynamic
8410667510a76409aca9bb24ff0eda0420088274Christian Maederupdate, DNSSEC, or even zone transfers.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian MaederOften, all you want is limited, read-only DNS access to an existing
8410667510a76409aca9bb24ff0eda0420088274Christian Maedersystem. For example, you may have an existing relational database
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettichcontaining hostname/address mappings and wish to provide forvard and
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian Maederreverse DNS lookups based on this information. Or perhaps you want to
3e61f574717499939bd8e0ff538ea9e7b72d4e2dKlaus Luettichset up a simple DNS-based load balancing system where the name server
3e61f574717499939bd8e0ff538ea9e7b72d4e2dKlaus Luettichanswers queries about a single DNS name with a dynamically changing
4d56f2fa72e4aec20eb827c11ed49c8cbb7014bdChristian Maederset of A records.
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian MaederBIND 9.1 introduced a new, simplified database interface, or "sdb",
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian Maederwhich greatly simplifies the writing of drivers for these kinds of
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian MaederThe sdb Driver
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian MaederAn sdb driver is an object module, typically written in C, which is
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian Maederlinked into the name server and registers itself with the sdb
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian Maedersubsystem. It provides a set of callback functions, which also serve
eee4b2ee739f163e09d6af6e45c025681e6c01a0Christian Maederto advertise its capabilities. When the name server receives DNS
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettichqueries, invokes the callback functions to obtain the data to respond
55adfe57a4de1f36adc3e3bfc16f342e44a7d444Christian MaederUnlike the full database interface, the sdb interface represents all
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maederdomain names and resource records as ASCII text.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian MaederWriting an sdb Driver
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian MaederWhen a driver is registered, it specifies its name, a list of callback
e7757995211bd395dc79d26fe017d99375f7d2a6Christian Maederfunctions, and flags.
0206ab93ef846e4e0885996d052b9b73b9dc66b0Christian MaederThe flags specify whether the driver wants to use relative domain
f13d1e86e58da53680e78043e8df182eed867efbChristian Maedernames where possible.
96646aed2ae087b942ae23f15bbe729a8f7c43d3Christian MaederThe callback functions are as follows. The only one that must be
e7757995211bd395dc79d26fe017d99375f7d2a6Christian Maederdefined is lookup().
c6fcd42c6d6d9dae8c7835c24fcb7ce8531a9050Christian Maeder - create(zone, argc, argv, driverdata, dbdata)
31c49f2fa23d4ac089f35145d80a224deb6ea7e4Till Mossakowski Create a database object for "zone".
36f63902db2b3463faa9f59912ad106e2d5aaa24Klaus Luettich - destroy(zone, driverdata, dbdata)
36f63902db2b3463faa9f59912ad106e2d5aaa24Klaus Luettich Destroy the database object for "zone".
8cacad2a09782249243b80985f28e9387019fe40Christian Maeder - lookup(zone, name, dbdata, lookup)
50515239e7e190f4a34ca581dd685d002148fbddChristian Maeder Return all the records at the domain name "name".
431d34c7007a787331c4e5ec997badb0f8190fc7Christian Maeder - authority(zone, dbdata, lookup)
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder Return the SOA and NS records at the zone apex.
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder - allnodes(zone, dbdata, allnodes)
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder Return all data in the zone, for zone transfers.
9e748851c150e1022fb952bab3315e869aaf0214Christian MaederFor more detail about these functions and their parameters, see
9e748851c150e1022fb952bab3315e869aaf0214Christian Maederbind9/lib/dns/include/dns/sdb.h. For example drivers, see
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian MaederRebuilding the Server
0206ab93ef846e4e0885996d052b9b73b9dc66b0Christian MaederThe driver module and header file must be copied to (or linked into)
9e748851c150e1022fb952bab3315e869aaf0214Christian Maederthe bind9/bin/named and bind9/bin/named/include directories
9e748851c150e1022fb952bab3315e869aaf0214Christian Maederrespectively, and must be added to the DBDRIVER_OBJS and DBDRIVER_SRCS
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maederlines in bin/named/Makefile.in (e.g. for the timedb sample sdb driver,
776a1a086df734581431e6edb4343ed4c8d34d55Christian Maederadd timedb.c to DBDRIVER_SRCS and timedb.@O@ to DBDRIVER_OBJS). If
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maederthe driver needs additional header files or libraries in nonstandard
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maederplaces, the DBDRIVER_INCLUDES and DBDRIVER_LIBS lines should also be
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian MaederCalls to dns_sdb_register() and dns_sdb_unregister() (or wrappers,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maedere.g. timedb_init() and timedb_clear() for the timedb sample sdb
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maederdriver) must be inserted into the server, in bind9/bin/named/main.c.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian MaederRegistration should be in setup(), before the call to
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maederns_server_create(). Unregistration should be in cleanup(),
9e748851c150e1022fb952bab3315e869aaf0214Christian Maederafter the call to ns_server_destroy(). A #include should be added
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maedercorresponding to the driver header file.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian MaederYou should try doing this with one or more of the sample drivers
c0c2380bced8159ff0297ece14eba948bd236471Christian Maederbefore attempting to write a driver of your own.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian MaederConfiguring the Server
4017ebc0f692820736d796af3110c3b3018c108aChristian MaederTo make a zone use a new database driver, specify a "database" option
62ea3d19927e5ce1318d62931a8427d8930f1576Christian Maederin its "zone" statement in named.conf. For example, if the driver
62ea3d19927e5ce1318d62931a8427d8930f1576Christian Maederregisters itself under the name "acmedb", you might say
6ff7a91875597d6e4dfaa68c79187d01473e8341Christian Maeder database "acmedb";
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian MaederYou can pass arbitrary arguments to the create() function of the
4017ebc0f692820736d796af3110c3b3018c108aChristian Maederdriver by adding any number of whitespace-separated words after the
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder database "acmedb -mode sql -connect 10.0.0.1";
a3c6d8e0670bf2aa71bc8e2a3b1f45d56dd65e4cChristian MaederHints for Driver Writers
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder - If a driver is generating data on the fly, it probably should
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder not implement the allnodes() function, since a zone transfer
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder will not be meaningful. The allnodes() function is more relevant
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder with data from a database.
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder - The authority() function is necessary if and only if the lookup()
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder function will not add SOA and NS records at the zone apex. If
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder SOA and NS records are provided by the lookup() function,
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder the authority() function should be NULL.
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder - When a driver is registered, an opaque object can be provided. This
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder object is passed into the database create() and destroy() functions.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder - When a database is created, an opaque object can be created that
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder is associated with that database. This object is passed into the
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder lookup(), authority(), and allnodes() functions, and is
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder destroyed by the destroy() function.
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian MaederFuture Directions
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian MaederA future release may support dynamic loading of sdb drivers.
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder$Id: sdb,v 1.6 2004/03/05 05:04:54 marka Exp $