README revision 62d63e5f02a5e7fcda59cf361149e3d7c78477be
70e5a7403f0e0a3bd292b8287c5fed5772c15270Automatic UpdaterDLZ (Dynamically Loadable Zones) is an extention to BIND 9 that
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrewsallows zone data to be retrieved directly from an external database.
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David LawrenceThere is no required format or schema. DLZ drivers exist for several
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updaterdifferent database backends including PostgreSQL, MySQL, and LDAP and
178f6ad061e54bc5babfca3577f72058fa0797c1Bob Halleycan be written for any other.
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David LawrenceHistorically, DLZ drivers had to be statically linked with the named
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrewsbinary and were turned on via a configure option at compile time (for
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrewsexample, "configure --with-dlz-ldap"). Currently, the drivers provided
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrewsin the BIND 9 tarball in contrib/dlz/drivers are still linked this way.
dafcb997e390efa4423883dafd100c975c4095d6Mark AndrewsHowever, as of BIND 9.8, it is also possible to link some DLZ modules
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrewsdynamically at runtime, via the DLZ "dlopen" driver, which acts as a
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrewsgeneric wrapper around a shared object that implements the DLZ API. The
b897c52f865b2fc4e220e2110b874e59c716456bBob Halley"dlopen" driver is linked into named by default, so configure options are
6dcb47e37f9f0cdb94bdabc3fa157ff07983c590Mark Andrewsno longer necessary unless using older DLZ drivers.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob HalleyWhen the DLZ module provides data to named, it does so in text format.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob HalleyThe response is converted to DNS wire format by named. This conversion,
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleyand the lack of any internal caching, places significant limits on the
460b427411b72da26b1836b9424e2e70d65d9394David Lawrencequery performance of DLZ modules. Consequently, DLZ is not recommended
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleyfor use on high-volume servers. However, it can be used in a hidden
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleymaster configuration, with slaves retrieving zone updates via AXFR.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley(Note, however, that DLZ has no built-in support for DNS notify; slaves
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleyare not automatically informed of changes to the zones in the database.)
b897c52f865b2fc4e220e2110b874e59c716456bBob HalleyCONFIGURING DLZ:
0b72c791466d0807bcf22522b5ddb7da902c2720Bob HalleyA DLZ database is configured with a "dlz" statement in named.conf.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley dlz example {
b897c52f865b2fc4e220e2110b874e59c716456bBob Halley database "dlopen driver.so <args>";
0b72c791466d0807bcf22522b5ddb7da902c2720Bob HalleyThis specifies a DLZ module to search when answering queries; the module
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleyis implemented in "driver.so" and is loaded at runtime by the dlopen DLZ
460b427411b72da26b1836b9424e2e70d65d9394David Lawrencedriver. Multiple "dlz" statements can be specified; when answering a
460b427411b72da26b1836b9424e2e70d65d9394David Lawrencequery, all DLZ modules with the "search" option set to "yes" will be
460b427411b72da26b1836b9424e2e70d65d9394David Lawrencechecked for an answer, and the best available answer will be returned
fcb54ce0a4f7377486df5bec83b3aa4711bf4131Mark Andrewsto the client.
460b427411b72da26b1836b9424e2e70d65d9394David LawrenceThe "search" option in this example can be omitted, as "yes" is the
460b427411b72da26b1836b9424e2e70d65d9394David Lawrencedefault value. If it is set to "no", then this DLZ module is *not*
460b427411b72da26b1836b9424e2e70d65d9394David Lawrencesearched for best-match when a query is received. Instead, zones in
460b427411b72da26b1836b9424e2e70d65d9394David Lawrencethis DLZ must be separately specified in a zone statement. This can
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleybe useful when conventional zone semantics are desired but you wish
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrenceto use a different back-end storage mechanism than the standard zone
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrencedatabase. For example, to use a DLZ module for an NXDOMAIN redirection
dabea86dac4c01f852b7aea728f73b4f55a89d44Mark Andrews database "dlopen driver.so <args>";
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence type redirect;
460b427411b72da26b1836b9424e2e70d65d9394David LawrenceEXAMPLE DRIVER:
8319af16557b81eba3277ee67215285f0823b587Mark AndrewsThis directory contains an example of an externally-lodable DLZ module,
8319af16557b81eba3277ee67215285f0823b587Mark Andrewsdlz_example.c, which demonstrates the features of the DLZ API. It sets up
aee5e9cbacd8f88325840b8a498876f4319b0890Mark Andrewsa single zone, whose name is configured in named.conf. The zone can answer
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrencequeries and AXFR requests, and accept DDNS updates.
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David LawrenceBy default, at runtime, the zone implemented by this driver will contain
460b427411b72da26b1836b9424e2e70d65d9394David Lawrencean SOA, NS, and a single A record at the apex. If configured in named.conf
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrenceto use the name "example.nil", then, the zone will look like this:
0014d6342b0d50ae37126ac16d5bf821d02ffff7David Lawrence example.nil. 3600 IN SOA example.nil. hostmaster.example.nil. (
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence 123 900 600 86400 3600
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrence example.nil. 1800 IN A 10.53.0.1
b719aabd6be52278f2cc426581179f3f3af36e20Mark AndrewsThe driver is also capable of retrieving information about the querying
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleyclient, and altering its response on the basis of this information. To
2320f230995995595438a9d9301d84931fd266ceMark Andrewsdemonstrate this feature, the example driver responds to queries for
c427260a8678f2e99a2337fb95ec98d9c9ee8c05Mark Andrews"source-addr.<zonename>/TXT" with the source address of the query.
6dcb47e37f9f0cdb94bdabc3fa157ff07983c590Mark AndrewsNote, however, that this record will *not* be included in AXFR or ANY
6dcb47e37f9f0cdb94bdabc3fa157ff07983c590Mark Andrewsresponses. (Normally, this feature would be used to alter responses in
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleysome other fashion, e.g., by providing different address records for
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleya particular name depending on the network from which the query arrived.)
0b72c791466d0807bcf22522b5ddb7da902c2720Bob HalleyIMPLEMENTATION NOTES:
0b72c791466d0807bcf22522b5ddb7da902c2720Bob HalleyThe minimal set of type definitions, prototypes, and macros needed
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleyfor implementing a DLZ driver is in ../modules/dlz_minimal.h. Copy this
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleyheader file into your source tree when creating an external DLZ module.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob HalleyThe DLZ dlopen driver provides a set of callback functions:
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley - void log(int level, const char *fmt, ...);
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley Writes the specified string to the named log, at the specified
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley log level. Uses printf() format semantics.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley - isc_result_t putrr(dns_sdlzlookup_t *lookup, const char *type,
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley dns_ttl_t ttl, const char *data);
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley Puts a DNS resource record into the query response, which
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley referenced by the opaque structure 'lookup' provided by named.
0014d6342b0d50ae37126ac16d5bf821d02ffff7David Lawrence - isc_result_t putnamedrr(dns_sdlzallnotes_t *allnodes,
0014d6342b0d50ae37126ac16d5bf821d02ffff7David Lawrence const char *name, const char *type,
0014d6342b0d50ae37126ac16d5bf821d02ffff7David Lawrence dns_ttl_t ttl, const char *data);
0014d6342b0d50ae37126ac16d5bf821d02ffff7David Lawrence Puts a DNS resource record into an AXFR response, which is
0014d6342b0d50ae37126ac16d5bf821d02ffff7David Lawrence referenced by the opaque structure 'allnodes' provided by named.
a9558a6c63d9c6dbb2f3800b39ccb008652fcde3Mark Andrews - isc_result_t writable_zone(dns_view_t *view, const char *zone_name);
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews Allows the DLZ module to inform named that a given zone can recieve
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews DDNS updates. (Note: This is not currently supported for DLZ
0014d6342b0d50ae37126ac16d5bf821d02ffff7David Lawrence databases that are configured as 'search no;')
0b72c791466d0807bcf22522b5ddb7da902c2720Bob HalleyThe external DLZ module can define the following functions (some of these
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halleyare mandatory, others optional).
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley - int dlz_version(unsigned int *flags);
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley Required for alL external DLZ modules, to indicate the version number
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley of the DLZ dlopen driver that this module supports. It should return
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley the value DLZ_DLOPEN_VERSION, which is defined in the file
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley contrib/dlz/modules/dlz_minimal.h and is currently 3. 'flags' is
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley updated to indicate capabilities of the module. In particular, if
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley the module is thread-safe then it sets 'flags' to include
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley DNS_SDLZFLAG_THREADSAFE. (Other capability flags may be added in
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley the future.)
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley - isc_result_t dlz_create(const char *dlzname,
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley unsigned int argc, char *argv[],
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley void **dbdata, ...);
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley Required for all external DLZ modules; this call initializes the
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley - void dlz_destroy(void *dbdata);
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley Optional. If supplied, this will be called when the driver is
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley - isc_result_t dlz_findzonedb(void *dbdata, const char *name,
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley dns_clientinfomethods_t *methods,
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley dns_clientinfo_t *clientinfo);
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley Required for all external DLZ modules. This indicates whether
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley the DLZ module can answer for the given name. Returns ISC_R_SUCCESS
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley if so, and ISC_R_NOTFOUND if not. As an optimization, it can
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley also return ISC_R_NOMORE: this indicates that the DLZ module has
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley no data for the given name or for any name above it in the DNS.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley This prevents named from searching for a zone cut.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley - isc_result_t dlz_lookup(const char *zone, const char *name, void *dbdata,
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley dns_sdlzlookup_t *lookup,
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley dns_clientinfomethods_t *methods,
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley dns_clientinfo_t *clientinfo);