The tinydns-data program

tinydns-data reads local DNS information from a file named data in the current directory. It creates data.cdb in a binary format designed for fast access by tinydns. It may also create some other files with names beginning with data.

tinydns-data updates data.cdb atomically, so you can use it safely while tinydns is running. If anything goes wrong with the creation of data.cdb, tinydns-data stops and leaves the old data.cdb in place.

Data format

The DNS information in data is a series of lines. There are several types of lines, as shown below.

Each line starts with a special character and continues with a series of colon-separated fields. In some cases the fields may be omitted; however, all colons must be included except at the end of the line. Spaces and tabs at the end of a line are ignored.

Each line ends with a ttl (``time to live'') specifying the number of seconds that the line's DNS records may be cached. Beware that cache times below 300 seconds will be treated as 300 by some clients, and NS cache times below 2 seconds can cause lookup failures. You may omit ttl; tinydns-data will use default cache times, carefully selected to work well in normal situations.

Common data lines

     .fqdn:ip:x:ttl

Name server for our domain fqdn. tinydns-data creates an NS record showing x.ns.fqdn as a name server for fqdn; an A record showing ip as the IP address of x.ns.fqdn; an SOA record for fqdn listing a.ns.fqdn as the primary name server and hostmaster@fqdn as the contact address; and NXDOMAIN responses for nonexistent names ending with .fqdn.

You may have several name servers for one domain, with a different x for each server. tinydns-data will generate only one SOA record per domain.

If x contains a dot then tinydns-data will use x as the server name rather than x.ns.fqdn. This feature is provided only for compatibility reasons; names not ending with fqdn will force clients to contact parent servers much more often than they otherwise would, and will reduce the overall reliability of DNS. You should omit ip if x has IP addresses assigned elsewhere in data.

     &fqdn:ip:x:ttl

Name server for delegated domain fqdn. tinydns-data creates referrals for names ending with .fqdn; these referrals include an NS record showing x.ns.fqdn as a name server for fqdn, and an A record showing ip as the IP address of x.ns.fqdn.

If x contains a dot then it is treated specially; see above.

You may have several name servers for one delegated domain, with a different x for each server.

     =fqdn:ip:ttl

Host fqdn with IP address ip. tinydns-data creates an A record showing ip as the IP address of fqdn, and a PTR record showing fqdn as the name of d.c.b.a.in-addr.arpa if ip is a.b.c.d.

You must specify name servers for some suffix of fqdn; otherwise tinydns-data will not generate its A record. Similarly, you must specify name servers for some suffix of d.c.b.a.in-addr.arpa; otherwise tinydns-data will not generate its PTR record. The same comments apply to other records described below.

     +fqdn:ip:ttl

Alias fqdn with IP address ip. This is just like =fqdn:ip:ttl except that tinydns-data generates only an A record.

     @fqdn:ip:x:dist:ttl

Mail exchanger for fqdn. tinydns-data creates an MX record showing x.mx.fqdn as a mail exchanger for fqdn at distance dist, and an A record showing ip as the IP address of x.mx.fqdn. You may omit dist; the default distance is 0.

If x contains a dot then it is treated specially; see above.

You may create several MX records for fqdn, with a different x for each server. Make sure to arrange for the SMTP server on each IP address to accept mail for fqdn.

     #comment

Comment line. The line is ignored.

Uncommon data lines

     'fqdn:s:ttl

TXT record for fqdn. tinydns-data creates a TXT record for fqdn containing the string s. You may use octal \nnn codes to include arbitrary bytes inside s; for example, \072 is a colon.

     ^fqdn:p:ttl

PTR record for fqdn. tinydns-data creates a PTR record for fqdn pointing to the domain name p.

     :fqdn:n:rdata:ttl

Generic record for fqdn. tinydns-data creates a record of type n for fqdn showing rdata. n must be an integer between 1 and 65535. The proper format of rdata depends on n. You may use octal \nnn codes to include arbitrary bytes inside rdata.

An example

Here is a typical data file:

     =lion.heaven.af.mil:1.2.3.4
     @heaven.af.mil:1.2.3.4
     @3.2.1.in-addr.arpa:1.2.3.4

     =tiger.heaven.af.mil:1.2.3.5
     .heaven.af.mil:1.2.3.5:a
     .3.2.1.in-addr.arpa:1.2.3.5:a

     =bear.heaven.af.mil:1.2.3.6
     .heaven.af.mil:1.2.3.6:b
     .3.2.1.in-addr.arpa:1.2.3.6:b

     =cheetah.heaven.af.mil:1.2.3.248
     =panther.heaven.af.mil:1.2.3.249

Here is the same information in traditional zone-file format (with the two zones merged):

     heaven.af.mil. 2560 IN SOA a.ns.heaven.af.mil. hostmaster.heaven.af.mil. ...
     heaven.af.mil. 259200 IN NS a.ns.heaven.af.mil.
     heaven.af.mil. 259200 IN NS b.ns.heaven.af.mil.
     heaven.af.mil. 86400 IN MX mx.heaven.af.mil.

     3.2.1.in-addr.arpa. 2560 IN SOA a.ns.3.2.1.in-addr.arpa. hostmaster.3.2.1.in-addr.arpa. ...
     3.2.1.in-addr.arpa. 259200 IN NS a.ns.3.2.1.in-addr.arpa.
     3.2.1.in-addr.arpa. 259200 IN NS b.ns.3.2.1.in-addr.arpa.
     3.2.1.in-addr.arpa. 86400 IN MX mx.3.2.1.in-addr.arpa.

     4.3.2.1.in-addr.arpa. 86400 IN PTR lion.heaven.af.mil.
     lion.heaven.af.mil. 86400 IN A 1.2.3.4
     mx.heaven.af.mil. 86400 IN A 1.2.3.4
     mx.3.2.1.in-addr.arpa. 86400 IN A 1.2.3.4

     5.3.2.1.in-addr.arpa. 86400 IN PTR tiger.heaven.af.mil.
     tiger.heaven.af.mil. 86400 IN A 1.2.3.5
     a.ns.heaven.af.mil. 259200 IN A 1.2.3.5
     a.ns.3.2.1.in-addr.arpa. 259200 IN A 1.2.3.5

     6.3.2.1.in-addr.arpa. 86400 IN PTR bear.heaven.af.mil.
     bear.heaven.af.mil. 86400 IN A 1.2.3.6
     b.ns.heaven.af.mil. 259200 IN A 1.2.3.6
     b.ns.3.2.1.in-addr.arpa. 259200 IN A 1.2.3.6

     248.3.2.1.in-addr.arpa. 86400 IN PTR cheetah.heaven.af.mil.
     cheetah.heaven.af.mil. 86400 IN A 1.2.3.248

     249.3.2.1.in-addr.arpa. 86400 IN PTR panther.heaven.af.mil.
     panther.heaven.af.mil. 86400 IN A 1.2.3.249

Further details

The cache time for negative responses (SOA records) is always 2560 seconds. The default cache time for NS records and their associated A records is 3 days. The default cache time for other records is 1 day.

tinydns-data, like BIND, includes NS records with answers to most queries. This increases DNS packet sizes, but it draws queries away from parent servers, and reduces the frequency of long DNS delays. With the default tinydns-data cache times, a client that uses a normal record at least once every day will always have the corresponding NS records cached and will never have to talk to parent servers.

tinydns-data creates NOTIMP responses to zone-transfer requests.

Design notes

The data format is very easy for programs to edit, and reasonably easy for humans to edit, unlike the traditional zone-file format.

tinydns-data could support a name wherever an IP address is required; it would look up the name in DNS and use the resulting address. This would reliably track changes in offsite IP addresses if the database were rebuilt periodically.

Time-to-live is a much less useful concept than time-to-die. If a machine is going to change IP addresses at 12:00, for example, then the old address should die at 12:00, and the new address should appear at 12:00. tinydns-data could support time-to-die but would need help from tinydns to dynamically convert time-to-die into the DNS protocol's time-to-live.

D. J. Bernstein

Internet publication