external/bsd/bind/dist/contrib/dlz/example/README

   1 OVERVIEW:
   2
   3 DLZ (Dynamically Loadable Zones) is an extention to BIND 9 that
   4 allows zone data to be retrieved directly from an external database.
   5 There is no required format or schema.  DLZ drivers exist for several
   6 different database backends including PostgreSQL, MySQL, and LDAP and
   7 can be written for any other.
   8
   9 Historically, DLZ drivers had to be statically linked with the named
  10 binary and were turned on via a configure option at compile time (for
  11 example, "configure --with-dlz-ldap").  Currently, the drivers provided
  12 in the BIND 9 tarball in contrib/dlz/drivers are still linked this way.
  13
  14 However, as of BIND 9.8, it is also possible to link some DLZ modules
  15 dynamically at runtime, via the DLZ "dlopen" driver, which acts as a
  16 generic wrapper around a shared object that implements the DLZ API.  The
  17 "dlopen" driver is linked into named by default, so configure options are
  18 no longer necessary unless using older DLZ drivers.
  19
  20 When the DLZ module provides data to named, it does so in text format.
  21 The response is converted to DNS wire format by named.  This conversion,
  22 and the lack of any internal caching, places significant limits on the
  23 query performance of DLZ modules.  Consequently, DLZ is not recommended
  24 for use on high-volume servers.  However, it can be used in a hidden
  25 master configuration, with slaves retrieving zone updates via AXFR.
  26 (Note, however, that DLZ has no built-in support for DNS notify; slaves
  27 are not automatically informed of changes to the zones in the database.)
  28
  29 CONFIGURING DLZ:
  30
  31 A DLZ database is configured with a "dlz" statement in named.conf.
  32
  33     dlz example {
  34         database "dlopen driver.so <args>";
  35         search yes;
  36     };
  37
  38 This specifies a DLZ module to search when answering queries; the module
  39 is implemented in "driver.so" and is loaded at runtime by the dlopen DLZ
  40 driver.  Multiple "dlz" statements can be specified; when answering a
  41 query, all DLZ modules with the "search" option set to "yes" will be
  42 checked for an answer, and the best available answer will be returned
  43 to the client.
  44
  45 The "search" option in this example can be omitted, as "yes" is the
  46 default value.  If it is set to "no", then this DLZ module is *not*
  47 searched for best-match when a query is received.  Instead, zones in
  48 this DLZ must be separately specified in a zone statement.  This can
  49 be useful when conventional zone semantics are desired but you wish
  50 to use a different back-end storage mechanism than the standard zone
  51 database.  For example, to use a DLZ module for an NXDOMAIN redirection
  52 zone:
  53
  54     dlz other {
  55         database "dlopen driver.so <args>";
  56         search no;
  57     };
  58
  59     zone "." {
  60         type redirect;
  61         dlz other;
  62     };
  63
  64 EXAMPLE DRIVER:
  65
  66 This directory contains an example of an externally-lodable DLZ module,
  67 dlz_example.c, which demonstrates the features of the DLZ API.  It sets up
  68 a single zone, whose name is configured in named.conf.  The zone can answer
  69 queries and AXFR requests, and accept DDNS updates.
  70
  71 By default, at runtime, the zone implemented by this driver will contain
  72 an SOA, NS, and a single A record at the apex.  If configured in named.conf
  73 to use the name "example.nil", then, the zone will look like this:
  74
  75  example.nil.  3600    IN      SOA     example.nil. hostmaster.example.nil. (
  76                                                123 900 600 86400 3600
  77                                        )
  78  example.nil.  3600    IN      NS      example.nil.
  79  example.nil.  1800    IN      A       10.53.0.1
  80
  81 The driver is also capable of retrieving information about the querying
  82 client, and altering its response on the basis of this information.  To
  83 demonstrate this feature, the example driver responds to queries for
  84 "source-addr.<zonename>/TXT" with the source address of the query.
  85 Note, however, that this record will *not* be included in AXFR or ANY
  86 responses.  (Normally, this feature would be used to alter responses in
  87 some other fashion, e.g., by providing different address records for
  88 a particular name depending on the network from which the query arrived.)
  89
  90 IMPLEMENTATION NOTES:
  91
  92 The minimal set of type definitions, prototypes, and macros needed
  93 for implementing a DLZ driver is in ../modules/dlz_minimal.h.  Copy this
  94 header file into your source tree when creating an external DLZ module.
  95
  96 The DLZ dlopen driver provides a set of callback functions:
  97
  98   - void log(int level, const char *fmt, ...);
  99
 100     Writes the specified string to the named log, at the specified
 101     log level.  Uses printf() format semantics.
 102
 103   - isc_result_t putrr(dns_sdlzlookup_t *lookup, const char *type,
 104                        dns_ttl_t ttl, const char *data);
 105
 106     Puts a DNS resource record into the query response, which
 107     referenced by the opaque structure 'lookup' provided by named.
 108
 109   - isc_result_t putnamedrr(dns_sdlzallnotes_t *allnodes,
 110                             const char *name, const char *type,
 111                             dns_ttl_t ttl, const char *data);
 112
 113     Puts a DNS resource record into an AXFR response, which is
 114     referenced by the opaque structure 'allnodes' provided by named.
 115
 116   - isc_result_t writeable_zone(dns_view_t *view, const char *zone_name);
 117
 118     Allows the DLZ module to inform named that a given zone can recieve
 119     DDNS updates.  (Note: This is not currently supported for DLZ
 120     databases that are configured as 'search no;')
 121
 122 The external DLZ module can define the following functions (some of these
 123 are mandatory, others optional).
 124
 125   - int dlz_version(unsigned int *flags);
 126
 127     Required for alL external DLZ modules, to indicate the version number
 128     of the DLZ dlopen driver that this module supports.  It should return
 129     the value DLZ_DLOPEN_VERSION, which is defined in the file
 130     contrib/dlz/modules/dlz_minimal.h and is currently 3.  'flags' is
 131     updated to indicate capabilities of the module.  In particular, if
 132     the module is thread-safe then it sets 'flags' to include
 133     DNS_SDLZFLAG_THREADSAFE.  (Other capability flags may be added in
 134     the future.)
 135
 136   - isc_result_t dlz_create(const char *dlzname,
 137                             unsigned int argc, char *argv[],
 138                             void **dbdata, ...);
 139
 140     Required for all external DLZ modules; this call initializes the
 141     module.
 142
 143   - void dlz_destroy(void *dbdata);
 144
 145     Optional.  If supplied, this will be called when the driver is
 146     unloaded.
 147
 148   - isc_result_t dlz_findzonedb(void *dbdata, const char *name,
 149                                 dns_clientinfomethods_t *methods,
 150                                 dns_clientinfo_t *clientinfo);
 151
 152     Required for all external DLZ modules.  This indicates whether
 153     the DLZ module can answer for the given name.  Returns ISC_R_SUCCESS
 154     if so, and ISC_R_NOTFOUND if not.  As an optimization, it can
 155     also return ISC_R_NOMORE: this indicates that the DLZ module has
 156     no data for the given name or for any name above it in the DNS.
 157     This prevents named from searching for a zone cut.
 158
 159    - isc_result_t dlz_lookup(const char *zone, const char *name, void *dbdata,
 160                              dns_sdlzlookup_t *lookup,
 161                              dns_clientinfomethods_t *methods,
 162                              dns_clientinfo_t *clientinfo);
 163
 164     Required for all external DLZ modules.  This carries out the database
 165     lookup for a query.
 166
 167   - isc_result_t dlz_allowzonexfr(void *dbdata, const char *name,
 168                                   const char *client);
 169
 170     Optional.  Supply this if you want the module to support AXFR
 171     for the specified zone and client.  A return value of ISC_R_SUCCESS
 172     means AXFR is allowed, any other value means it isn't.
 173
 174   -  isc_result_t dlz_allnodes(const char *zone, void *dbdata,
 175                                dns_sdlzallnodes_t *allnodes);
 176
 177      Optional, but must be supplied dlz_allowzonexfr() is.  This function
 178      returns all nodes in the zone in order to perform a zone transfer.
 179
 180   - isc_result_t dlz_newversion(const char *zone, void *dbdata,
 181                                 void **versionp);
 182
 183     Optional.  Supply this if you want the module to support DDNS
 184     updates.  This function starts a transaction in the database.
 185
 186
 187   - void dlz_closeversion(const char *zone, isc_boolean_t commit,
 188                           void *dbdata, void **versionp);
 189
 190     Optional, but must be supplied if dlz_newversion() is.  This function
 191     closes a transaction.  'commit' indicates whether to commit the changes
 192     to the database, or ignore them.
 193
 194   - isc_result_t dlz_configure(dns_view_t *view, void *dbdata);
 195
 196     Optional, but must be supplied in order to support DDNS updates.
 197
 198   - isc_boolean_t dlz_ssumatch(const char *signer, const char *name,
 199                                const char *tcpaddr, const char *type,
 200                                const char *key, uint32_t keydatalen,
 201                                uint8_t *keydata, void *dbdata);
 202
 203     Optional, but must be supplied in order to support DDNS updates.
 204
 205   - isc_result_t dlz_addrdataset(const char *name, const char *rdatastr,
 206                                  void *dbdata, void *version);
 207
 208     Optional, but must be supplied in order to support DDNS updates.
 209     Adds the data in 'rdatastr' to a database node.
 210
 211   - isc_result_t dlz_subrdataset(const char *name, const char *rdatastr,
 212                                  void *dbdata, void *version);
 213
 214     Optional, but must be supplied in order to support DDNS updates.
 215     Removes the data in 'rdatastr' from a database node.
 216
 217   - isc_result_t dlz_delrdataset(const char *name, const char *rdatastr,
 218                                  void *dbdata, void *version);
 219
 220     Optional, but must be supplied in order to support DDNS updates.
 221     Deletes all data matching the type specified in 'rdatastr' from
 222     the database.