/contrib/bind9/doc/misc/sdb

https://bitbucket.org/freebsd/freebsd-head/ · #! · 169 lines · 121 code · 48 blank · 0 comment · 0 complexity · 961f6be06043afaf9e263646bc8e95bc MD5 · raw file

  1. Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
  2. Copyright (C) 2000, 2001 Internet Software Consortium.
  3. See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
  4. Using the BIND 9 Simplified Database Interface
  5. This document describes the care and feeding of the BIND 9 Simplified
  6. Database Interface, which allows you to extend BIND 9 with new ways
  7. of obtaining the data that is published as DNS zones.
  8. The Original BIND 9 Database Interface
  9. BIND 9 has a well-defined "back-end database interface" that makes it
  10. possible to replace the component of the name server responsible for
  11. the storage and retrieval of zone data, called the "database", on a
  12. per-zone basis. The default database is an in-memory, red-black-tree
  13. data structure commonly referred to as "rbtdb", but it is possible to
  14. write drivers to support any number of alternative database
  15. technologies such as in-memory hash tables, application specific
  16. persistent on-disk databases, object databases, or relational
  17. databases.
  18. The original BIND 9 database interface defined in <dns/db.h> is
  19. designed to efficiently support the full set of database functionality
  20. needed by a name server that implements the complete DNS protocols,
  21. including features such as zone transfers, dynamic update, and DNSSEC.
  22. Each of these aspects of name server operations places its own set of
  23. demands on the data store, with the result that the database API is
  24. quite complex and contains operations that are highly specific to the
  25. DNS. For example, data are stored in a binary format, the name space
  26. is tree structured, and sets of data records are conceptually
  27. associated with DNSSEC signature sets. For these reasons, writing a
  28. driver using this interface is a highly nontrivial undertaking.
  29. The Simplified Database Interface
  30. Many BIND users wish to provide access to various data sources through
  31. the DNS, but are not necessarily interested in completely replacing
  32. the in-memory "rbt" database or in supporting features like dynamic
  33. update, DNSSEC, or even zone transfers.
  34. Often, all you want is limited, read-only DNS access to an existing
  35. system. For example, you may have an existing relational database
  36. containing hostname/address mappings and wish to provide forvard and
  37. reverse DNS lookups based on this information. Or perhaps you want to
  38. set up a simple DNS-based load balancing system where the name server
  39. answers queries about a single DNS name with a dynamically changing
  40. set of A records.
  41. BIND 9.1 introduced a new, simplified database interface, or "sdb",
  42. which greatly simplifies the writing of drivers for these kinds of
  43. applications.
  44. The sdb Driver
  45. An sdb driver is an object module, typically written in C, which is
  46. linked into the name server and registers itself with the sdb
  47. subsystem. It provides a set of callback functions, which also serve
  48. to advertise its capabilities. When the name server receives DNS
  49. queries, invokes the callback functions to obtain the data to respond
  50. with.
  51. Unlike the full database interface, the sdb interface represents all
  52. domain names and resource records as ASCII text.
  53. Writing an sdb Driver
  54. When a driver is registered, it specifies its name, a list of callback
  55. functions, and flags.
  56. The flags specify whether the driver wants to use relative domain
  57. names where possible.
  58. The callback functions are as follows. The only one that must be
  59. defined is lookup().
  60. - create(zone, argc, argv, driverdata, dbdata)
  61. Create a database object for "zone".
  62. - destroy(zone, driverdata, dbdata)
  63. Destroy the database object for "zone".
  64. - lookup(zone, name, dbdata, lookup)
  65. Return all the records at the domain name "name".
  66. - authority(zone, dbdata, lookup)
  67. Return the SOA and NS records at the zone apex.
  68. - allnodes(zone, dbdata, allnodes)
  69. Return all data in the zone, for zone transfers.
  70. For more detail about these functions and their parameters, see
  71. bind9/lib/dns/include/dns/sdb.h. For example drivers, see
  72. bind9/contrib/sdb.
  73. Rebuilding the Server
  74. The driver module and header file must be copied to (or linked into)
  75. the bind9/bin/named and bind9/bin/named/include directories
  76. respectively, and must be added to the DBDRIVER_OBJS and DBDRIVER_SRCS
  77. lines in bin/named/Makefile.in (e.g. for the timedb sample sdb driver,
  78. add timedb.c to DBDRIVER_SRCS and timedb.@O@ to DBDRIVER_OBJS). If
  79. the driver needs additional header files or libraries in nonstandard
  80. places, the DBDRIVER_INCLUDES and DBDRIVER_LIBS lines should also be
  81. updated.
  82. Calls to dns_sdb_register() and dns_sdb_unregister() (or wrappers,
  83. e.g. timedb_init() and timedb_clear() for the timedb sample sdb
  84. driver) must be inserted into the server, in bind9/bin/named/main.c.
  85. Registration should be in setup(), before the call to
  86. ns_server_create(). Unregistration should be in cleanup(),
  87. after the call to ns_server_destroy(). A #include should be added
  88. corresponding to the driver header file.
  89. You should try doing this with one or more of the sample drivers
  90. before attempting to write a driver of your own.
  91. Configuring the Server
  92. To make a zone use a new database driver, specify a "database" option
  93. in its "zone" statement in named.conf. For example, if the driver
  94. registers itself under the name "acmedb", you might say
  95. zone "foo.com" {
  96. database "acmedb";
  97. };
  98. You can pass arbitrary arguments to the create() function of the
  99. driver by adding any number of whitespace-separated words after the
  100. driver name:
  101. zone "foo.com" {
  102. database "acmedb -mode sql -connect 10.0.0.1";
  103. };
  104. Hints for Driver Writers
  105. - If a driver is generating data on the fly, it probably should
  106. not implement the allnodes() function, since a zone transfer
  107. will not be meaningful. The allnodes() function is more relevant
  108. with data from a database.
  109. - The authority() function is necessary if and only if the lookup()
  110. function will not add SOA and NS records at the zone apex. If
  111. SOA and NS records are provided by the lookup() function,
  112. the authority() function should be NULL.
  113. - When a driver is registered, an opaque object can be provided. This
  114. object is passed into the database create() and destroy() functions.
  115. - When a database is created, an opaque object can be created that
  116. is associated with that database. This object is passed into the
  117. lookup(), authority(), and allnodes() functions, and is
  118. destroyed by the destroy() function.
  119. Future Directions
  120. A future release may support dynamic loading of sdb drivers.
  121. $Id: sdb,v 1.6 2004/03/05 05:04:54 marka Exp $