9336f01769f16a8eda79340094d663db0f8537c7Evan HuntDLZ (Dynamically Loadable Zones) is an extention to BIND 9 that
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntallows zone data to be retrieved directly from an external database.
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntThere is no required format or schema. DLZ drivers exist for several
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntdifferent database backends including PostgreSQL, MySQL, and LDAP and
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntcan be written for any other.
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntHistorically, DLZ drivers had to be statically linked with the named
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntbinary and were turned on via a configure option at compile time (for
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntexample, "configure --with-dlz-ldap"). Currently, the drivers provided
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntin the BIND 9 tarball in contrib/dlz/drivers are still linked this way.
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntHowever, as of BIND 9.8, it is also possible to link some DLZ modules
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntdynamically at runtime, via the DLZ "dlopen" driver, which acts as a
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntgeneric wrapper around a shared object that implements the DLZ API. The
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt"dlopen" driver is linked into named by default, so configure options are
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntno longer necessary unless using older DLZ drivers.
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntWhen the DLZ module provides data to named, it does so in text format.
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntThe response is converted to DNS wire format by named. This conversion,
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntand the lack of any internal caching, places significant limits on the
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntquery performance of DLZ modules. Consequently, DLZ is not recommended
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntfor use on high-volume servers. However, it can be used in a hidden
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntmaster configuration, with slaves retrieving zone updates via AXFR.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt(Note, however, that DLZ has no built-in support for DNS notify; slaves
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntare not automatically informed of changes to the zones in the database.)
2b8bed6681d1541474f022586cbe728dfce36880Evan HuntCONFIGURING DLZ:
2b8bed6681d1541474f022586cbe728dfce36880Evan HuntA DLZ database is configured with a "dlz" statement in named.conf.
2b8bed6681d1541474f022586cbe728dfce36880Evan Hunt dlz example {
2b8bed6681d1541474f022586cbe728dfce36880Evan Hunt database "dlopen driver.so <args>";
2b8bed6681d1541474f022586cbe728dfce36880Evan HuntThis specifies a DLZ module to search when answering queries; the module
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntis implemented in "driver.so" and is loaded at runtime by the dlopen DLZ
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntdriver. Multiple "dlz" statements can be specified; when answering a
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntquery, all DLZ modules with the "search" option set to "yes" will be
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntchecked for an answer, and the best available answer will be returned
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntto the client.
2b8bed6681d1541474f022586cbe728dfce36880Evan HuntThe "search" option in this example can be omitted, as "yes" is the
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntdefault value. If it is set to "no", then this DLZ module is *not*
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntsearched for best-match when a query is received. Instead, zones in
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntthis DLZ must be separately specified in a zone statement. This can
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntbe useful when conventional zone semantics are desired but you wish
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntto use a different back-end storage mechanism than the standard zone
2b8bed6681d1541474f022586cbe728dfce36880Evan Huntdatabase. For example, to use a DLZ module for an NXDOMAIN redirection
2b8bed6681d1541474f022586cbe728dfce36880Evan Hunt database "dlopen driver.so <args>";
2b8bed6681d1541474f022586cbe728dfce36880Evan Hunt type redirect;
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntEXAMPLE DRIVER:
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntThis directory contains an example of an externally-lodable DLZ module,
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntdlz_example.c, which demonstrates the features of the DLZ API. It sets up
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunta single zone, whose name is configured in named.conf. The zone can answer
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntqueries and AXFR requests, and accept DDNS updates.
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntBy default, at runtime, the zone implemented by this driver will contain
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntan SOA, NS, and a single A record at the apex. If configured in named.conf
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntto use the name "example.nil", then, the zone will look like this:
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt example.nil. 3600 IN SOA example.nil. hostmaster.example.nil. (
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt 123 900 600 86400 3600
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt example.nil. 1800 IN A 10.53.0.1
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntThe driver is also capable of retrieving information about the querying
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntclient, and altering its response on the basis of this information. To
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntdemonstrate this feature, the example driver responds to queries for
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt"source-addr.<zonename>/TXT" with the source address of the query.
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntNote, however, that this record will *not* be included in AXFR or ANY
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntresponses. (Normally, this feature would be used to alter responses in
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntsome other fashion, e.g., by providing different address records for
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunta particular name depending on the network from which the query arrived.)
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan HuntDYNAMIC UPDATES AND TRANSACTIONS:
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan HuntIf a DLZ module wants to implement dynamic DNS updates (DDNS), the
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Huntnormal calling sequence is
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Hunt - dlz_newversion (start a 'transaction')
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Hunt - dlz_addrdataset (add records)
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Hunt - dlz_subrdataset (remove records)
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Hunt - dlz_closeversion (end a 'transaction')
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan HuntHowever, BIND may also query the database during the transaction
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Hunt(e.g., to check prerequisites), and your DLZ might need to know whether
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Huntthe lookup is against the pre-existing data, or the new data.
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Huntdlz_lookup() doesn't give you access to the 'versionp' pointer
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Huntdirectly, so it must be passed via 'clientinfo' structure if
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Huntit is needed.
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan HuntThe dlz_example.c code has sample code to show how to get the 'versionp'
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Huntpointer from within dlz_lookup(). If it's set to NULL, we query
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Huntthe standard database; if non-NULL, we query against the in-flight
aefb3e308ba01ad47a3d3aaadf77a5edd4261cb9Evan Huntdata within the appropriate uncommitted transaction.
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntIMPLEMENTATION NOTES:
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntThe minimal set of type definitions, prototypes, and macros needed
62d63e5f02a5e7fcda59cf361149e3d7c78477beEvan Huntfor implementing a DLZ driver is in ../modules/dlz_minimal.h. Copy this
62d63e5f02a5e7fcda59cf361149e3d7c78477beEvan Huntheader file into your source tree when creating an external DLZ module.
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntThe DLZ dlopen driver provides a set of callback functions:
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - void log(int level, const char *fmt, ...);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Writes the specified string to the named log, at the specified
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt log level. Uses printf() format semantics.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_result_t putrr(dns_sdlzlookup_t *lookup, const char *type,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt dns_ttl_t ttl, const char *data);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Puts a DNS resource record into the query response, which
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt referenced by the opaque structure 'lookup' provided by named.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_result_t putnamedrr(dns_sdlzallnotes_t *allnodes,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt const char *name, const char *type,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt dns_ttl_t ttl, const char *data);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Puts a DNS resource record into an AXFR response, which is
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt referenced by the opaque structure 'allnodes' provided by named.
be7d3e641c1f426185cc65950c8b587a3365f038Mukund Sivaraman - isc_result_t writeable_zone(dns_view_t *view, const char *zone_name);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Allows the DLZ module to inform named that a given zone can recieve
2b8bed6681d1541474f022586cbe728dfce36880Evan Hunt DDNS updates. (Note: This is not currently supported for DLZ
2b8bed6681d1541474f022586cbe728dfce36880Evan Hunt databases that are configured as 'search no;')
9336f01769f16a8eda79340094d663db0f8537c7Evan HuntThe external DLZ module can define the following functions (some of these
9336f01769f16a8eda79340094d663db0f8537c7Evan Huntare mandatory, others optional).
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - int dlz_version(unsigned int *flags);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Required for alL external DLZ modules, to indicate the version number
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt of the DLZ dlopen driver that this module supports. It should return
62d63e5f02a5e7fcda59cf361149e3d7c78477beEvan Hunt the value DLZ_DLOPEN_VERSION, which is defined in the file
62d63e5f02a5e7fcda59cf361149e3d7c78477beEvan Hunt contrib/dlz/modules/dlz_minimal.h and is currently 3. 'flags' is
62d63e5f02a5e7fcda59cf361149e3d7c78477beEvan Hunt updated to indicate capabilities of the module. In particular, if
62d63e5f02a5e7fcda59cf361149e3d7c78477beEvan Hunt the module is thread-safe then it sets 'flags' to include
62d63e5f02a5e7fcda59cf361149e3d7c78477beEvan Hunt DNS_SDLZFLAG_THREADSAFE. (Other capability flags may be added in
62d63e5f02a5e7fcda59cf361149e3d7c78477beEvan Hunt the future.)
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_result_t dlz_create(const char *dlzname,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt unsigned int argc, char *argv[],
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt void **dbdata, ...);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Required for all external DLZ modules; this call initializes the
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - void dlz_destroy(void *dbdata);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Optional. If supplied, this will be called when the driver is
5b1fe44f1ef505375d1a30a0a25e25f8dfabddceEvan Hunt - isc_result_t dlz_findzonedb(void *dbdata, const char *name,
5b1fe44f1ef505375d1a30a0a25e25f8dfabddceEvan Hunt dns_clientinfomethods_t *methods,
5b1fe44f1ef505375d1a30a0a25e25f8dfabddceEvan Hunt dns_clientinfo_t *clientinfo);
2db105b04c05f523ab0a4ad031e65bc4aa138085Evan Hunt Required for all external DLZ modules. This indicates whether
2db105b04c05f523ab0a4ad031e65bc4aa138085Evan Hunt the DLZ module can answer for the given name. Returns ISC_R_SUCCESS
2db105b04c05f523ab0a4ad031e65bc4aa138085Evan Hunt if so, and ISC_R_NOTFOUND if not. As an optimization, it can
2db105b04c05f523ab0a4ad031e65bc4aa138085Evan Hunt also return ISC_R_NOMORE: this indicates that the DLZ module has
2db105b04c05f523ab0a4ad031e65bc4aa138085Evan Hunt no data for the given name or for any name above it in the DNS.
2db105b04c05f523ab0a4ad031e65bc4aa138085Evan Hunt This prevents named from searching for a zone cut.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_result_t dlz_lookup(const char *zone, const char *name, void *dbdata,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt dns_sdlzlookup_t *lookup,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt dns_clientinfomethods_t *methods,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt dns_clientinfo_t *clientinfo);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Required for all external DLZ modules. This carries out the database
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt lookup for a query.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_result_t dlz_allowzonexfr(void *dbdata, const char *name,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt const char *client);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Optional. Supply this if you want the module to support AXFR
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt for the specified zone and client. A return value of ISC_R_SUCCESS
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt means AXFR is allowed, any other value means it isn't.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_result_t dlz_allnodes(const char *zone, void *dbdata,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt dns_sdlzallnodes_t *allnodes);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Optional, but must be supplied dlz_allowzonexfr() is. This function
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt returns all nodes in the zone in order to perform a zone transfer.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_result_t dlz_newversion(const char *zone, void *dbdata,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt void **versionp);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Optional. Supply this if you want the module to support DDNS
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt updates. This function starts a transaction in the database.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - void dlz_closeversion(const char *zone, isc_boolean_t commit,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt void *dbdata, void **versionp);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Optional, but must be supplied if dlz_newversion() is. This function
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt closes a transaction. 'commit' indicates whether to commit the changes
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt to the database, or ignore them.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_result_t dlz_configure(dns_view_t *view, void *dbdata);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Optional, but must be supplied in order to support DDNS updates.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_boolean_t dlz_ssumatch(const char *signer, const char *name,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt const char *tcpaddr, const char *type,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt const char *key, uint32_t keydatalen,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt uint8_t *keydata, void *dbdata);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Optional, but must be supplied in order to support DDNS updates.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_result_t dlz_addrdataset(const char *name, const char *rdatastr,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt void *dbdata, void *version);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Optional, but must be supplied in order to support DDNS updates.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Adds the data in 'rdatastr' to a database node.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_result_t dlz_subrdataset(const char *name, const char *rdatastr,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt void *dbdata, void *version);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Optional, but must be supplied in order to support DDNS updates.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Removes the data in 'rdatastr' from a database node.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt - isc_result_t dlz_delrdataset(const char *name, const char *rdatastr,
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt void *dbdata, void *version);
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Optional, but must be supplied in order to support DDNS updates.
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt Deletes all data matching the type specified in 'rdatastr' from
9336f01769f16a8eda79340094d663db0f8537c7Evan Hunt the database.