external/bsd/bind/dist/doc/arm/dlz.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3  - Copyright (C) 2012-2014  Internet Systems Consortium, Inc. ("ISC")
   4  -
   5  - Permission to use, copy, modify, and/or distribute this software for any
   6  - purpose with or without fee is hereby granted, provided that the above
   7  - copyright notice and this permission notice appear in all copies.
   8  -
   9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17
  18 <!-- Id -->
  19
  20 <sect1 id="dlz-info">
  21   <title>DLZ (Dynamically Loadable Zones)</title>
  22   <para>
  23     DLZ (Dynamically Loadable Zones) is an extension to BIND 9 that allows
  24     zone data to be retrieved directly from an external database.  There is
  25     no required format or schema.  DLZ drivers exist for several different
  26     database backends including PostgreSQL, MySQL, and LDAP and can be
  27     written for any other.
  28   </para>
  29   <para>
  30     Historically, DLZ drivers had to be statically linked with the named
  31     binary and were turned on via a configure option at compile time (for
  32     example, <userinput>"configure --with-dlz-ldap"</userinput>).
  33     Currently, the drivers provided in the BIND 9 tarball in
  34     <filename>contrib/dlz/drivers</filename> are still linked this
  35     way.
  36   </para>
  37   <para>
  38     In BIND 9.8 and higher, it is possible to link some DLZ modules
  39     dynamically at runtime, via the DLZ "dlopen" driver, which acts as a
  40     generic wrapper around a shared object implementing the DLZ API.  The
  41     "dlopen" driver is linked into named by default, so configure options
  42     are no longer necessary when using these dynamically linkable drivers,
  43     but are still needed for the older drivers in
  44     <filename>contrib/dlz/drivers</filename>.
  45   </para>
  46
  47   <para>
  48     When the DLZ module provides data to named, it does so in text format.
  49     The response is converted to DNS wire format by named.  This
  50     conversion, and the lack of any internal caching, places significant
  51     limits on the query performance of DLZ modules.  Consequently, DLZ is
  52     not recommended for use on high-volume servers.  However, it can be
  53     used in a hidden master configuration, with slaves retrieving zone
  54     updates via AXFR.  (Note, however, that DLZ has no built-in support for
  55     DNS notify; slaves are not automatically informed of changes to the
  56     zones in the database.)
  57   </para>
  58
  59   <sect2>
  60     <title>Configuring DLZ</title>
  61     <para>
  62       A DLZ database is configured with a <command>dlz</command>
  63       statement in <filename>named.conf</filename>:
  64     </para>
  65     <screen>
  66     dlz example {
  67         database "dlopen driver.so <option>args</option>";
  68         search yes;
  69     };
  70     </screen>
  71     <para>
  72       This specifies a DLZ module to search when answering queries; the
  73       module is implemented in <filename>driver.so</filename> and is
  74       loaded at runtime by the dlopen DLZ driver.  Multiple
  75       <command>dlz</command> statements can be specified; when
  76       answering a query, all DLZ modules with <option>search</option>
  77       set to <literal>yes</literal> will be queried to find out if
  78       they contain an answer for the query name; the best available
  79       answer will be returned to the client.
  80     </para>
  81     <para>
  82       The <option>search</option> option in the above example can be
  83       omitted, because <literal>yes</literal> is the default value.
  84     </para>
  85     <para>
  86       If <option>search</option> is set to <literal>no</literal>, then
  87       this DLZ module is <emphasis>not</emphasis> searched for the best
  88       match when a query is received.  Instead, zones in this DLZ must be
  89       separately specified in a zone statement.  This allows you to
  90       configure a zone normally using standard zone option semantics,
  91       but specify a different database back-end for storage of the
  92       zone's data.  For example, to implement NXDOMAIN redirection using
  93       a DLZ module for back-end storage of redirection rules:
  94     </para>
  95     <screen>
  96     dlz other {
  97         database "dlopen driver.so <option>args</option>";
  98         search no;
  99     };
 100
 101     zone "." {
 102         type redirect;
 103         dlz other;
 104     };
 105     </screen>
 106   </sect2>
 107   <sect2>
 108     <title>Sample DLZ Driver</title>
 109     <para>
 110       For guidance in implementation of DLZ modules, the directory
 111       <filename>contrib/dlz/example</filename> contains a basic
 112       dynamically-linkable DLZ module--i.e., one which can be
 113       loaded at runtime by the "dlopen" DLZ driver.
 114       The example sets up a single zone, whose name is passed
 115       to the module as an argument in the <command>dlz</command>
 116       statement:
 117     </para>
 118     <screen>
 119     dlz other {
 120         database "dlopen driver.so example.nil";
 121     };
 122     </screen>
 123     <para>
 124       In the above example, the module is configured to create a zone
 125       "example.nil", which can answer queries and AXFR requests, and
 126       accept DDNS updates.  At runtime, prior to any updates, the zone
 127       contains an SOA, NS, and a single A record at the apex:
 128     </para>
 129     <screen>
 130  example.nil.  3600    IN      SOA     example.nil. hostmaster.example.nil. (
 131                                                123 900 600 86400 3600
 132                                        )
 133  example.nil.  3600    IN      NS      example.nil.
 134  example.nil.  1800    IN      A       10.53.0.1
 135     </screen>
 136     <para>
 137       The sample driver is capable of retrieving information about the
 138       querying client, and altering its response on the basis of this
 139       information.  To demonstrate this feature, the example driver
 140       responds to queries for "source-addr.<option>zonename</option>>/TXT"
 141       with the source address of the query.  Note, however, that this
 142       record will *not* be included in AXFR or ANY responses.  Normally,
 143       this feature would be used to alter responses in some other fashion,
 144       e.g., by providing different address records for a particular name
 145       depending on the network from which the query arrived.
 146     </para>
 147     <para>
 148       Documentation of the DLZ module API can be found in
 149       <filename>contrib/dlz/example/README</filename>.  This directory also
 150       contains the header file <filename>dlz_minimal.h</filename>, which
 151       defines the API and should be included by any dynamically-linkable
 152       DLZ module.
 153     </para>
 154   </sect2>
 155 </sect1>