diff options
Diffstat (limited to 'doc/arm/dlz.inc.rst')
| -rw-r--r-- | doc/arm/dlz.inc.rst | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/doc/arm/dlz.inc.rst b/doc/arm/dlz.inc.rst new file mode 100644 index 0000000..b6f7473 --- /dev/null +++ b/doc/arm/dlz.inc.rst @@ -0,0 +1,129 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. 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. + +.. _dlz-info: + +Dynamically Loadable Zones (DLZ) +-------------------------------- + +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 modules exist for several different +database backends, including MySQL and LDAP, and can be +written for any other. + +The DLZ module provides data to :iscman:`named` in text +format, which is then converted to DNS wire format by :iscman:`named`. 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. + +Configuring DLZ +~~~~~~~~~~~~~~~ +.. namedconf:statement:: dlz + :tags: zone + :short: Configures a Dynamically Loadable Zone (DLZ) database in :iscman:`named.conf`. + +A DLZ database is configured with a :any:`dlz` statement in :iscman:`named.conf`: + +:: + + dlz example { + database "dlopen driver.so args"; + search yes; + }; + + +This specifies a DLZ module to search when answering queries; the module +is implemented in ``driver.so`` and is loaded at runtime by the dlopen +DLZ driver. Multiple :any:`dlz` statements can be specified. + + +.. namedconf:statement:: search + :tags: query + :short: Specifies whether a Dynamically Loadable Zone (DLZ) module is queried for an answer to a query name. + +When answering a query, all DLZ modules with :namedconf:ref:`search` set to ``yes`` are +queried to see whether they contain an answer for the query name. The best +available answer is returned to the client. + +The :namedconf:ref:`search` option in the above example can be omitted, because +``yes`` is the default value. + +If :namedconf:ref:`search` is set to ``no``, this DLZ module is *not* 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: + +:: + + dlz other { + database "dlopen driver.so args"; + search no; + }; + + zone "." { + type redirect; + dlz other; + }; + + +Sample DLZ Module +~~~~~~~~~~~~~~~~~ + +For guidance in the implementation of DLZ modules, the directory +``contrib/dlz/example`` 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 :any:`dlz` statement: + +:: + + dlz other { + database "dlopen driver.so example.nil"; + }; + + +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: + +:: + + 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 + + +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.``zonename``>/TXT" with the source address of +the query. Note, however, that this record will *not* 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. + +Documentation of the DLZ module API can be found in +``contrib/dlz/example/README``. This directory also contains the header +file ``dlz_minimal.h``, which defines the API and should be included by +any dynamically linkable DLZ module. |