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