1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
2..
3.. SPDX-License-Identifier: MPL-2.0
4..
5.. This Source Code Form is subject to the terms of the Mozilla Public
6.. License, v. 2.0.  If a copy of the MPL was not distributed with this
7.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
8..
9.. See the COPYRIGHT file distributed with this work for additional
10.. information regarding copyright ownership.
11
12.. _dlz-info:
13
14Dynamically Loadable Zones (DLZ)
15--------------------------------
16
17Dynamically Loadable Zones (DLZ) are an extension to BIND 9 that allows
18zone data to be retrieved directly from an external database. There is
19no required format or schema. DLZ drivers exist for several different
20database backends, including PostgreSQL, MySQL, and LDAP, and can be
21written for any other.
22
23Historically, DLZ drivers had to be statically linked with the ``named``
24binary and were turned on via a configure option at compile time (for
25example, ``configure --with-dlz-ldap``). The drivers
26provided in the BIND 9 tarball in ``contrib/dlz/drivers`` are still
27linked this way.
28
29In BIND 9.8 and higher, it is possible to link some DLZ modules
30dynamically at runtime, via the DLZ "dlopen" driver, which acts as a
31generic wrapper around a shared object implementing the DLZ API. The
32"dlopen" driver is linked into ``named`` by default, so configure
33options are no longer necessary when using these dynamically linkable
34drivers; they are still needed for the older drivers in
35``contrib/dlz/drivers``.
36
37The DLZ module provides data to ``named`` in text
38format, which is then converted to DNS wire format by ``named``. This
39conversion, and the lack of any internal caching, places significant
40limits on the query performance of DLZ modules. Consequently, DLZ is not
41recommended for use on high-volume servers. However, it can be used in a
42hidden primary configuration, with secondaries retrieving zone updates via
43AXFR. Note, however, that DLZ has no built-in support for DNS notify;
44secondary servers are not automatically informed of changes to the zones in the
45database.
46
47Configuring DLZ
48~~~~~~~~~~~~~~~
49
50A DLZ database is configured with a ``dlz`` statement in ``named.conf``:
51
52::
53
54       dlz example {
55       database "dlopen driver.so args";
56       search yes;
57       };
58
59
60This specifies a DLZ module to search when answering queries; the module
61is implemented in ``driver.so`` and is loaded at runtime by the dlopen
62DLZ driver. Multiple ``dlz`` statements can be specified; when answering
63a query, all DLZ modules with ``search`` set to ``yes`` are queried
64to see whether they contain an answer for the query name. The best
65available answer is returned to the client.
66
67The ``search`` option in the above example can be omitted, because
68``yes`` is the default value.
69
70If ``search`` is set to ``no``, this DLZ module is *not* searched
71for the best match when a query is received. Instead, zones in this DLZ
72must be separately specified in a zone statement. This allows users to
73configure a zone normally using standard zone-option semantics, but
74specify a different database backend for storage of the zone's data.
75For example, to implement NXDOMAIN redirection using a DLZ module for
76backend storage of redirection rules:
77
78::
79
80       dlz other {
81              database "dlopen driver.so args";
82              search no;
83       };
84
85       zone "." {
86              type redirect;
87              dlz other;
88       };
89
90
91Sample DLZ Driver
92~~~~~~~~~~~~~~~~~
93
94For guidance in the implementation of DLZ modules, the directory
95``contrib/dlz/example`` contains a basic dynamically linkable DLZ
96module - i.e., one which can be loaded at runtime by the "dlopen" DLZ
97driver. The example sets up a single zone, whose name is passed to the
98module as an argument in the ``dlz`` statement:
99
100::
101
102       dlz other {
103              database "dlopen driver.so example.nil";
104       };
105
106
107In the above example, the module is configured to create a zone
108"example.nil", which can answer queries and AXFR requests and accept
109DDNS updates. At runtime, prior to any updates, the zone contains an
110SOA, NS, and a single A record at the apex:
111
112::
113
114    example.nil.  3600    IN      SOA     example.nil. hostmaster.example.nil. (
115                              123 900 600 86400 3600
116                          )
117    example.nil.  3600    IN      NS      example.nil.
118    example.nil.  1800    IN      A       10.53.0.1
119
120
121The sample driver can retrieve information about the
122querying client and alter its response on the basis of this
123information. To demonstrate this feature, the example driver responds to
124queries for "source-addr.``zonename``>/TXT" with the source address of
125the query. Note, however, that this record will *not* be included in
126AXFR or ANY responses. Normally, this feature is used to alter
127responses in some other fashion, e.g., by providing different address
128records for a particular name depending on the network from which the
129query arrived.
130
131Documentation of the DLZ module API can be found in
132``contrib/dlz/example/README``. This directory also contains the header
133file ``dlz_minimal.h``, which defines the API and should be included by
134any dynamically linkable DLZ module.
135