README revision 9336f01769f16a8eda79340094d663db0f8537c7
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark AndrewsDLZ (Dynamically Loadable Zones) is an extention to BIND 9 that
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinallows zone data to be retrieved directly from an external database.
4a14ce5ba00ab7bc55c99ffdcf59c7a4ab902721Automatic UpdaterThere is no required format or schema. DLZ drivers exist for several
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeindifferent database backends including PostgreSQL, MySQL, and LDAP and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeincan be written for any other.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinHistorically, DLZ drivers had to be statically linked with the named
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinbinary and were turned on via a configure option at compile time (for
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinexample, "configure --with-dlz-ldap"). Currently, the drivers provided
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinin the BIND 9 tarball in contrib/dlz/drivers are still linked this way.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinHowever, as of BIND 9.8, it is also possible to link some DLZ modules
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeindynamically at runtime, via the DLZ "dlopen" driver, which acts as a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeingeneric wrapper around a shared object that implements the DLZ API. The
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein"dlopen" driver is linked into named by default, so configure options are
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinno longer necessary.
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox UserWhen the DLZ module provides data to named, it does so in text format.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserThe response is converted to DNS wire format by named. This conversion,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntand the lack of any internal caching, places significant limits on the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinquery performance of DLZ modules. Consequently, DLZ is not recommended
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinfor use on high-volume servers. However, it can be used in a hidden
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox Usermaster configuration, with slaves retrieving zone updates via AXFR.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein(Note, however, that DLZ has no built-in support for DNS notify; slaves
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinare not automatically informed of changes to the zones in the database.)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinEXAMPLE DRIVER:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThis directory contains an example of an externally-lodable DLZ module,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeindlz_example.c, which demonstrates the features of the DLZ API. It sets up
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeina single zone, whose name is configured in named.conf. The zone can answer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinqueries and AXFR requests, and accept DDNS updates.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsBy default, at runtime, the zone implemented by this driver will contain
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinan SOA, NS, and a single A record at the apex. If configured in named.conf
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinto use the name "example.nil", then, the zone will look like this:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein example.nil. 3600 IN SOA example.nil. hostmaster.example.nil. (
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User 123 900 600 86400 3600
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt example.nil. 1800 IN A 10.53.0.1
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserThe driver is also capable of retrieving information about the querying
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userclient, and altering its response on the basis of this information. To
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntdemonstrate this feature, the example driver responds to queries for
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt"source-addr.<zonename>/TXT" with the source address of the query.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntNote, however, that this record will *not* be included in AXFR or ANY
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntresponses. (Normally, this feature would be used to alter responses in
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntsome other fashion, e.g., by providing different address records for
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunta particular name depending on the network from which the query arrived.)
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntIMPLEMENTATION NOTES:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThe minimal set of type definitions, prototypes, and macros needed
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntfor implementing a DLZ driver is in dlz_minimal.h. Copy this header
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntfile into your source tree when creating an external DLZ module.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserThe DLZ dlopen driver provides a set of callback functions:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - void log(int level, const char *fmt, ...);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Writes the specified string to the named log, at the specified
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User log level. Uses printf() format semantics.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - isc_result_t putrr(dns_sdlzlookup_t *lookup, const char *type,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt dns_ttl_t ttl, const char *data);
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Puts a DNS resource record into the query response, which
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt referenced by the opaque structure 'lookup' provided by named.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - isc_result_t putnamedrr(dns_sdlzallnotes_t *allnodes,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt const char *name, const char *type,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User dns_ttl_t ttl, const char *data);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Puts a DNS resource record into an AXFR response, which is
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt referenced by the opaque structure 'allnodes' provided by named.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - isc_result_t writable_zone(dns_view_t *view, const char *zone_name);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Allows the DLZ module to inform named that a given zone can recieve
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt DDNS updates.
c42708dcc8ca18a41152251654d29f0cdd5b9533Tinderbox UserThe external DLZ module can define the following functions (some of these
c42708dcc8ca18a41152251654d29f0cdd5b9533Tinderbox Userare mandatory, others optional).
c42708dcc8ca18a41152251654d29f0cdd5b9533Tinderbox User - int dlz_version(unsigned int *flags);
dec590a3deb8e87380a8bd3a77d535dba3729bf6Tinderbox User Required for alL external DLZ modules, to indicate the version number
c42708dcc8ca18a41152251654d29f0cdd5b9533Tinderbox User of the DLZ dlopen driver that this module supports. It should return
2ba8603ca962450068fe45f04c5caf8219b0d5f1Tinderbox User the value DLZ_DLOPEN_VERSION, which is defined in dlz_minimal.h and
2ba8603ca962450068fe45f04c5caf8219b0d5f1Tinderbox User is currently 2. 'flags' is updated to indicate capabilities
2ba8603ca962450068fe45f04c5caf8219b0d5f1Tinderbox User of the module. In particular, if the module is thread-safe then it
2ba8603ca962450068fe45f04c5caf8219b0d5f1Tinderbox User sets 'flags' to include DNS_SDLZFLAG_THREADSAFE. (Other capability
2ba8603ca962450068fe45f04c5caf8219b0d5f1Tinderbox User flags may be added in the future.)
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - isc_result_t dlz_create(const char *dlzname,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt unsigned int argc, char *argv[],
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt void **dbdata, ...);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Required for all external DLZ modules; this call initializes the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - void dlz_destroy(void *dbdata);
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Optional. If supplied, this will be called when the driver is
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - isc_result_t dlz_findzonedb(void *dbdata, const char *name);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Required for all external DLZ modules. This indicates whether the
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User DLZ module can answer for a given zone. Returns ISC_R_SUCCESS if
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt so, otherwise ISC_R_NOTFOUND.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - isc_result_t dlz_lookup(const char *zone, const char *name, void *dbdata,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User dns_sdlzlookup_t *lookup,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt dns_clientinfomethods_t *methods,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt dns_clientinfo_t *clientinfo);
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Required for all external DLZ modules. This carries out the database
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt lookup for a query.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - isc_result_t dlz_allowzonexfr(void *dbdata, const char *name,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt const char *client);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Optional. Supply this if you want the module to support AXFR
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User for the specified zone and client. A return value of ISC_R_SUCCESS
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt means AXFR is allowed, any other value means it isn't.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - isc_result_t dlz_allnodes(const char *zone, void *dbdata,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User dns_sdlzallnodes_t *allnodes);
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Optional, but must be supplied dlz_allowzonexfr() is. This function
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt returns all nodes in the zone in order to perform a zone transfer.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - isc_result_t dlz_newversion(const char *zone, void *dbdata,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt void **versionp);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Optional. Supply this if you want the module to support DDNS
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt updates. This function starts a transaction in the database.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - void dlz_closeversion(const char *zone, isc_boolean_t commit,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt void *dbdata, void **versionp);
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Optional, but must be supplied if dlz_newversion() is. This function
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt closes a transaction. 'commit' indicates whether to commit the changes
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt to the database, or ignore them.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - isc_result_t dlz_configure(dns_view_t *view, void *dbdata);
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Optional, but must be supplied in order to support DDNS updates.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - isc_boolean_t dlz_ssumatch(const char *signer, const char *name,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt const char *tcpaddr, const char *type,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt const char *key, uint32_t keydatalen,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt uint8_t *keydata, void *dbdata);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Optional, but must be supplied in order to support DDNS updates.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - isc_result_t dlz_addrdataset(const char *name, const char *rdatastr,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User void *dbdata, void *version);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Optional, but must be supplied in order to support DDNS updates.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Adds the data in 'rdatastr' to a database node.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - isc_result_t dlz_subrdataset(const char *name, const char *rdatastr,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt void *dbdata, void *version);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Optional, but must be supplied in order to support DDNS updates.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User Removes the data in 'rdatastr' from a database node.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - isc_result_t dlz_delrdataset(const char *name, const char *rdatastr,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt void *dbdata, void *version);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Optional, but must be supplied in order to support DDNS updates.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt Deletes all data matching the type specified in 'rdatastr' from
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt the database.