bind9/doc/arm/dlz.xml

<!--
 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
 -
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, you can obtain one at https://mozilla.org/MPL/2.0/.
 -
 - See the COPYRIGHT file distributed with this work for additional
 - information regarding copyright ownership.
-->

<!-- Converted by db4-upgrade version 1.0 -->
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dlz-info"><info><title>DLZ (Dynamically Loadable Zones)</title></info>

  <para>
    Dynamically Loadable Zones (DLZ) are an extension to BIND 9 that allows
    zone data to be retrieved directly from an external database.  There is
    no required format or schema.  DLZ drivers exist for several different
    database backends, including PostgreSQL, MySQL, and LDAP, and can be
    written for any other.
  </para>
  <para>
    Historically, DLZ drivers had to be statically linked with the <command>named</command>
    binary and were turned on via a configure option at compile time (for
    example, <userinput>configure --with-dlz-ldap</userinput>).
    The drivers provided in the BIND 9 tarball in
    <filename>contrib/dlz/drivers</filename> are still linked this
    way.
  </para>
  <para>
    In BIND 9.8 and higher, it is possible to link some DLZ modules
    dynamically at runtime, via the DLZ "dlopen" driver, which acts as a
    generic wrapper around a shared object implementing the DLZ API.  The
    "dlopen" driver is linked into <command>named</command> by default, so configure options
    are no longer necessary when using these dynamically linkable drivers;
    they are still needed for the older drivers in
    <filename>contrib/dlz/drivers</filename>.
  </para>

  <para>
    The DLZ module provides data to <command>named</command> in text format,
    which is then converted to DNS wire format by <command>named</command>.  This
    conversion, and the lack of any internal caching, places significant
    limits on the query performance of DLZ modules.  Consequently, DLZ is
    not recommended for use on high-volume servers.  However, it can be
    used in a hidden primary configuration, with secondaries retrieving zone
    updates via AXFR.  Note, however, that DLZ has no built-in support for
    DNS notify; secondary servers are not automatically informed of changes to the
    zones in the database.
  </para>

  <section><info><title>Configuring DLZ</title></info>

    <para>
      A DLZ database is configured with a <command>dlz</command>
      statement in <filename>named.conf</filename>:
    </para>
    <screen>
    dlz example {
	database "dlopen driver.so <option>args</option>";
	search yes;
    };
    </screen>
    <para>
      This specifies a DLZ module to search when answering queries; the
      module is implemented in <filename>driver.so</filename> and is
      loaded at runtime by the dlopen DLZ driver.  Multiple
      <command>dlz</command> statements can be specified; when
      answering a query, all DLZ modules with <option>search</option>
      set to <literal>yes</literal> are queried to see whether
      they contain an answer for the query name. The best available
      answer is returned to the client.
    </para>
    <para>
      The <option>search</option> option in the above example can be
      omitted, because <literal>yes</literal> is the default value.
    </para>
    <para>
      If <option>search</option> is set to <literal>no</literal>, then
      this DLZ module is <emphasis>not</emphasis> searched for the best
      match when a query is received.  Instead, zones in this DLZ must be
      separately specified in a zone statement.  This allows users to
      configure a zone normally using standard zone-option semantics,
      but specify a different database backend for storage of the
      zone's data.  For example, to implement NXDOMAIN redirection using
      a DLZ module for backend storage of redirection rules:
    </para>
    <screen>
    dlz other {
	database "dlopen driver.so <option>args</option>";
	search no;
    };

    zone "." {
	type redirect;
	dlz other;
    };
    </screen>
  </section>
  <section><info><title>Sample DLZ Driver</title></info>

    <para>
      For guidance in the implementation of DLZ modules, the directory
      <filename>contrib/dlz/example</filename> contains a basic
      dynamically linkable DLZ module - i.e., one which can be
      loaded at runtime by the "dlopen" DLZ driver.
      The example sets up a single zone, whose name is passed
      to the module as an argument in the <command>dlz</command>
      statement:
    </para>
    <screen>
    dlz other {
	database "dlopen driver.so example.nil";
    };
    </screen>
    <para>
      In the above example, the module is configured to create a zone
      "example.nil", which can answer queries and AXFR requests and
      accept DDNS updates.  At runtime, prior to any updates, the zone
      contains an SOA, NS, and a single A record at the apex:
    </para>
    <screen>
 example.nil.  3600    IN      SOA     example.nil. hostmaster.example.nil. (
					       123 900 600 86400 3600
				       )
 example.nil.  3600    IN      NS      example.nil.
 example.nil.  1800    IN      A       10.53.0.1
    </screen>
    <para>
      The sample driver can retrieve information about the
      querying client and alter its response on the basis of this
      information.  To demonstrate this feature, the example driver
      responds to queries for "source-addr.<option>zonename</option>&gt;/TXT"
      with the source address of the query.  Note, however, that this
      record will <emphasis>not</emphasis> be included in AXFR or ANY responses.  Normally,
      this feature is used to alter responses in some other fashion,
      e.g., by providing different address records for a particular name
      depending on the network from which the query arrived.
    </para>
    <para>
      Documentation of the DLZ module API can be found in
      <filename>contrib/dlz/example/README</filename>.  This directory also
      contains the header file <filename>dlz_minimal.h</filename>, which
      defines the API and should be included by any dynamically linkable
      DLZ module.
    </para>
  </section>
</section>