the djb way

djbdns


tinydns data

In the previous section we used the tinydns add-* utilities to make some initial entries into a tinydns database:

# cd /service/tinydns/root
# ./add-ns example.org 1.2.3.4
# ./add-host alice.example.org 1.2.3.4
# ./add-host betty.example.org 1.2.3.5
# ./add-host carol.example.org 1.2.3.6
# ./add-mx example.org 1.2.3.4
# ./add-alias www.example.org 1.2.3.5
# make

This command sequence configures tinydns entries for a network with three hosts:

The add-* utilities simply append each entry to a plain-text file named /service/tinydns/root/data. The make command then converts the plain-text data to a fast-hashing cdb file named data.cdb.

Now we are interested in looking into the plain-text file, data. This is what we will see after the original add-* entries shown above:

# cat data
.example.org:1.2.3.4:a:259200
=alice.example.org:1.2.3.4:86400
=betty.example.org:1.2.3.5:86400
=carol.example.org:1.2.3.6:86400
@example.org:1.2.3.4:a::86400
+www.example.org:1.2.3.5:86400

In other words, each ./add-* command puts a corresponding line into the data file:

./add-* utility... ...data line
./add-ns example.org 1.2.3.4 .example.org:1.2.3.4:a:259200
./add-host alice.example.org 1.2.3.4 =alice.example.org:1.2.3.4:86400
./add-host betty.example.org 1.2.3.5 =betty.example.org:1.2.3.5:86400
./add-host carol.example.org 1.2.3.6 =carol.example.org:1.2.3.6:86400
./add-mx example.org 1.2.3.4 @example.org:1.2.3.4:a::86400
./add-alias www.example.org 1.2.3.5 +www.example.org:1.2.3.5:86400

The data file consists of a set of heterogeneous record types, with one record per line. Each record type is indicated by the first character of the record. The data file shown here has 4 types of records:

The actual data for each record follows the record-type character, and consists of a set of colon-delimited (':') fields. Each record type is defined with its own set of fields. That is, while field definitions are similar among different types of records, the order and type of fields in a record are specific to that record type.

In practice, the add-* utilities are useful only to create an initial set of template entries into the data file. After that, for any maintenance beyond the initial setup, it is easier to work with the data file directly, using the yank/paste features of a text editor to quickly make additional entries as required.

Notice also that there are no corresponding del-* or mod-* utilities provided, to delete or modify tinydns record entries. And some record types are not supplied with add-* utilities at all, including text, cname, and generic records. Again, for this kind of maintenance and modification, you simply edit the plain-text data file directly.

So where can you find the definitions for all the specific tinydns record types? There is no better place than from djb himself: http://cr.yp.to/djbdns/tinydns-data.html. Here's a summary of the most common for quick reference:

prefix description field specs DNS records created ./add-* util
. nameserver .domain:ip:xname:ttl:tai64:loc NS, A, SOA ./add-ns domain ip
& nameserver
delegation
&domain:ip:xname:ttl:tai64:loc NS, A  
= hostname =hostname:ip:ttl:tai64:loc A, PTR ./add-host hostname ip
+ alias +hostname:ip:ttl:tai64:loc A ./add-alias hostname ip
@ mail exchanger @domain:ip:xname:distance:ttl:tai64:loc MX, A ./add-mx domain ip
' text 'fqdn:string:ttl:tai64:loc TXT  
^ PTR ^ip-in.addr.arpa:fqdn:ttl:tai64:loc PTR  
% location %loc:ipnet    
# comment      

Notes:

Note also that tinydns is pretty smart, and will generate more than one DNS resource record when appropriate. For example, a tinydns '=' record will generate both A and PTR resource records automatically. Here is a quick reference to some of the most common DNS resource record types:

type code description purpose
A 1 "address" hostname --> address
NS 2 "nameserver" nameserver for domain
CNAME 5 "canonical name" use A records instead!
SOA 6 "start of authority" authority for domain
PTR 12 "pointer" address --> hostname
MX 15 "mail exchanger" SMTP host for domain
TXT 16 "text" hostname --> anystring

The numerical codes shown in this table are the numbers seen in response to queries with dnsq. For example, in the query:

$ dnsq mx example.org 1.2.3.4
15 example.org:
101 bytes, 1+1+1+2 records, response, authoritative, noerror
query: 15 example.org
answer: example.org 86400 MX 0 a.mx.example.org
authority: example.org 259200 NS a.ns.example.org
additional: a.mx.example.org 86400 A 1.2.3.4
additional: a.ns.example.org 259200 A 1.2.3.4

The '15' displayed in response lines refers to the MX record type. (Resource records and type codes are defined by the RFCs covering DNS, in this case RFC 1035.)

A few other comments:

One last reminder: don't forget to run make after editing data! The changes will be immediately available; no need to restart the tinydns service.


Copyright © 2002, 2003, 2004, Wayne Marshall.
All rights reserved.

Last edit 2004.06.01, wcm.