Documentation – BIND 9 XMLRPC DLZ Driver


Bind's DLZ is an API that allows dynamic production of zone information that is served by BIND. This driver uses that API in order to  build a bridge between bind and a convenient XML format served over HTTP. Using this you can manage your DNS data using any web application environment you choose.


After applying the patch you will need to run “aclocal; autoconf” afterwards to adjust the  configure and Makefile files to support the new driver. This is the version 1 patch. It is licensed under the GPLv2.


BIND Confguration and Compilation

  •  Requires LibXML2 (http://xmlsoft.org/) development packages
  •  Fedora Core 8 Packages libxml2 and libxml2-devel
  •  sudo yum install libxml2 libxml2-devel
  • Ubuntu 8.04 packages libxml2 and libxml2-dev
  •  sudo apt-get install libxml2 libxml2-dev

Once libxml2 is installed...

  • ./configure –with-dlz-xmlrpc [ANY OTHER CONFIG OPTIONS]
  •  --enable-threads is a recommended option to get full parallelism. XMLRPC-DLZ is thread safe
  •  make
  •  you should be left with bind-9.[blah]/bin/named/named as the executable

Executing

  •  BIND can be installed and run in any of the usual ways with any of the normal options
  •  I have run as “sudo bin/named/named -c dlz.conf”
  •  My dlz.conf has no options other than the required information for the dlz driver:


dlz "dlz_example" {
database "dlz_xmlrpc
url http://book.ducksong.com/xmlrpc/
refresh-key invalidateme
neg-cache-ttl 60
";
};


  • the url is the only required parameter
  • At runtime the querystring “?zone=ZONENAME” will be appended to the url in order to dynamically lookup ZONENAME
  • The refresh-key parameter specifies the DNS name that triggers a reload of that zone in the driver, refreshing the driver cache. looking up any record type with this name in the zone has that side effect. The lookup will return results as normal (e.g. invalidateme.example.com). The default is "refresh-key".
  • The neg-cache-ttl parameter is important because it indicates to the driver how long to cache the fact that a zone does not exist in the web application. This is important because BIND generates a lot of failed zone requests internally. For example consider the case of being configured to serve up the zone "zone.com". In order to lookup the A record of www.zone.com, bind first asks the dlz driver if it supports the "www.zone.com" zone. The driver is supposed to respond "no" and then BIND internally asks "what about zone.com" to which the driver can say yes. Failure to cache that first part would be overwhelming for your web application. neg-cache-ttl defaults to 1 day (86400). All cached invalid zones are removed from the cache whenever any particular zone is manually refreshed.



XML format


<?xml version="1.0"?>
<!-- sample zone configuration for xmlrpc bind dlz driver - r002
mcmanus@ducksong.com, Thurs May 01 2008
-->
<zone>
<!-- the name is optional and must match the
requested zone if provided
-->
<name>m12345.com</name>
<!-- the soa element is optional, if it is not
provided defaults are used for all fields.
Pay special attention to serial number management. If
you do not manage it in the usual way, xmlrpc dlz driver
will substitute time_t(NOW) for it, which will work fine
but will result in a zone xfer to any secondaries each time
the zone expires from cache or bind is restarted
defaults for refresh, retry, expire, and minimum are taken
from RFC 1537 and are 8hr, 2hr, 7days, and 1 day repsectively
The default TTL is 7200 (2hrs).
The BIND DLZ driver framework has a limitation that effectively
requires all records within the zone to have the same TTL
value. This is the DNS TTL value returned to DNS clients, not the
DLZ driver cache management of the entire zone. Because of this
limitation all records in this zone will inherit the SOA TTL value.
-->
<soa>
<serial>973</serial>
<refresh>36000</refresh>
<retry>7200</retry>
<expire>86400</expire>
<minimum>86000</minimum>
<ttl>3600</ttl>
</soa>
<!-- 0 or more ns elements,
each ns record has exactly 1 host element and an optional name element
name identifes the local name in this zone for the record, and
host identies the nameserver host.
if the ns record applies to the apex (the zone itself) you may
either omit the name element or use the value @
the host element has an optional attribute: style
style maybe be either "relative" or "fqdn", default is
relative. a bind style trailing dot on fqdn's is optional
as the dlz driver will put it there if it is missing in the
xml. relative hosts with a trailing dot are treated as if they
are fqdn.
In the example, ns1.m12345.com and ns-external.l123.com are
nameservers for the m12345.com zone. While ns1.m12345.com is also
a nameserver for the subdomain.m12345.com zone (which would have
its contents defined in its own xml file)
-->
<ns>
<host>ns1</host>
</ns>
<ns>
<name>@</name>
<host style="fqdn">ns-limey.ducksong.com</host>
</ns>
<ns>
<name>subdomain</name>
<host style="fqdn">localhost.ducksong.com</host>
</ns>
<!-- 0 or more mx elements,
each with exactly 1 host element and an optional name element and
optional priority elements. Priority elements default to 10 if not
provided. Name elements default to the apex, apex may also be
represented by @
The host element uses the same attribute as the ns host element
-->
<mx>
<host style="relative">mx1</host>
</mx>
<mx>
<host>mx2.externalnameserver.com.</host>
</mx>
<mx>
<name>www</name>
<host>mx1</host>
</mx>
<!-- 0 or more a record elements,
each with 1 or more addr element and an optional name element.
Name elements default to the apex, apex may also be
represented by @
the addresses are dotted decimal ipv4 representations
-->
<a>
<name>ns1</name>
<addr>10.1.1.1</addr>
</a>
<a>
<name>n2</name>
<addr>10.1.1.2</addr>
</a>
<a>
<name>mx1</name>
<addr>10.1.1.3</addr>
</a>
<a>
<name>ftp</name>
<addr>10.1.2.1</addr>
</a>
<a>
<!-- this has 3 DNS A records for www -
it would also be acceptable to place this is 3 different a
elements in the xml file all with the name www
-->
<name>www</name>
<addr>10.1.3.1</addr>
<addr>10.1.3.2</addr>
<addr>10.1.3.3</addr>
</a>
<!-- 0 or more txt elements,
each with exactly 1 text element and an optional name element.
Name elements default to the apex, apex may also be
represented by @.
The TXT value will be double quoted by the driver
-->
<txt>
<name>@</name>
<text>v=spf1 ip4:10.1.1.0/24 -all</text>
</txt>
<txt>
<name>www</name>
<text>note about my webserver</text>
</txt>
<!-- 0 or more cname elements,
each with exactly 1 host element and an optional name element.
Name elements default to the apex, apex may also be
represented by @.
The host element uses the same attribute as the ns host element.
-->
<cname>
<name>web</name>
<host>www</host>
</cname>
<!-- 0 or more ptr elements
each with exactly 1 host element and an optional name element.
Name elements default to the apex, apex may also be
represented by @.
The host element uses the same attribute as the ns host element.
There are no ptr elements in this example zone because it is
a forward zone. Only reverse zones typically have ptr records.
-->
<!-- Finally, the zonettl and zonetransfer elements provide some
optional metadata used by the dlz driver.
-->
<!-- zonettl is the number of seconds the zone will be cached within
the driver (or until explicitly invalidated with the
refresh-key). The default is 86400 (one day)
-->
<zonettl>200</zonettl>
<!-- zone transfer establishes the whitelist of secondary nameservers
that are allowed to pull this zone. It is analagous to the
allow-transfer configuration in named.conf
-->
<zonetransfer>
<addr>192.168.16.3</addr>
<addr>192.168.16.210</addr>
<addr>127.0.0.1</addr>
</zonetransfer>
</zone>


Notes


The driver is fully SMP safe, make sure to compile BIND with –enable-threads or BIND will not operate that way. When everything is in cache the driver uses a reader/writer locking scheme that allows multiple queries to form DNS responses from the same data simultaneously.


When a zone needs to be fetched from the database because the zone is expired only the first request will wait for the refetch – overlapping requests will use the “expired” zone information instead. This saves wear and tear on the database. In the case where there is no expired zone (i.e. The first transfer) there will still only be one query made to the database and all of the overlapping queries will use its result to form their response. Expired valid zones are only replaced with invalid zones if the valid zone was explicitly invalidated – never because of time based expiration. In the case of an expired zone that cannot be refreshed from the database the stale zone will continue to be used, expiring every minute and trying again.