4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsCopyright (C) 2000, 2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThis Source Code Form is subject to the terms of the Mozilla Public

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntLicense, v. 2.0. If a copy of the MPL was not distributed with this

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntfile, You can obtain one at http://mozilla.org/MPL/2.0/.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntUsing the BIND 9 Simplified Database Interface

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThis document describes the care and feeding of the BIND 9 Simplified

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntDatabase Interface, which allows you to extend BIND 9 with new ways

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntof obtaining the data that is published as DNS zones.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThe Original BIND 9 Database Interface

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntBIND 9 has a well-defined "back-end database interface" that makes it

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntpossible to replace the component of the name server responsible for

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntthe storage and retrieval of zone data, called the "database", on a

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntper-zone basis. The default database is an in-memory, red-black-tree

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntdata structure commonly referred to as "rbtdb", but it is possible to

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntwrite drivers to support any number of alternative database

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunttechnologies such as in-memory hash tables, application specific

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntpersistent on-disk databases, object databases, or relational

4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsdatabases.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThe original BIND 9 database interface defined in <dns/db.h> is

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntdesigned to efficiently support the full set of database functionality

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntneeded by a name server that implements the complete DNS protocols,

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntincluding features such as zone transfers, dynamic update, and DNSSEC.

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntEach of these aspects of name server operations places its own set of

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntdemands on the data store, with the result that the database API is

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntquite complex and contains operations that are highly specific to the

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntDNS. For example, data are stored in a binary format, the name space

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntis tree structured, and sets of data records are conceptually

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntassociated with DNSSEC signature sets. For these reasons, writing a

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntdriver using this interface is a highly nontrivial undertaking.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThe Simplified Database Interface

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntMany BIND users wish to provide access to various data sources through

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntthe DNS, but are not necessarily interested in completely replacing

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntthe in-memory "rbt" database or in supporting features like dynamic

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntupdate, DNSSEC, or even zone transfers.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntOften, all you want is limited, read-only DNS access to an existing

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntsystem. For example, you may have an existing relational database

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntcontaining hostname/address mappings and wish to provide forvard and

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntreverse DNS lookups based on this information. Or perhaps you want to

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntset up a simple DNS-based load balancing system where the name server

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntanswers queries about a single DNS name with a dynamically changing

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntset of A records.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntBIND 9.1 introduced a new, simplified database interface, or "sdb",

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntwhich greatly simplifies the writing of drivers for these kinds of

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntapplications.

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThe sdb Driver

ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt

ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntAn sdb driver is an object module, typically written in C, which is

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntlinked into the name server and registers itself with the sdb

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntsubsystem. It provides a set of callback functions, which also serve

ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntto advertise its capabilities. When the name server receives DNS

4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsqueries, invokes the callback functions to obtain the data to respond

with.

Unlike the full database interface, the sdb interface represents all

domain names and resource records as ASCII text.

Writing an sdb Driver

When a driver is registered, it specifies its name, a list of callback

functions, and flags.

The flags specify whether the driver wants to use relative domain

names where possible.

The callback functions are as follows. The only one that must be

defined is lookup().

- create(zone, argc, argv, driverdata, dbdata)

Create a database object for "zone".

- destroy(zone, driverdata, dbdata)

Destroy the database object for "zone".

- lookup(zone, name, dbdata, lookup)

Return all the records at the domain name "name".

- 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

bind9/lib/dns/include/dns/sdb.h. For example drivers, see

bind9/contrib/sdb.

Rebuilding the Server

The driver module and header file must be copied to (or linked into)

the bind9/bin/named and bind9/bin/named/include directories

respectively, and must be added to the DBDRIVER_OBJS and DBDRIVER_SRCS

lines in bin/named/Makefile.in (e.g. for the timedb sample sdb driver,

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

updated.

Calls to dns_sdb_register() and dns_sdb_unregister() (or wrappers,

e.g. timedb_init() and timedb_clear() for the timedb sample sdb

driver) must be inserted into the server, in bind9/bin/named/main.c.

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.

Configuring the Server

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

zone "foo.com" {

database "acmedb";

};

You can pass arbitrary arguments to the create() function of the

driver by adding any number of whitespace-separated words after the

driver name:

zone "foo.com" {

database "acmedb -mode sql -connect 10.0.0.1";

};

Hints for Driver Writers

- 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.

Future Directions

A future release may support dynamic loading of sdb drivers.

$Id: sdb,v 1.6 2004/03/05 05:04:54 marka Exp $