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.
Each line starts with a special character and continues with a series of vertical-bar separated fields. In some cases the fields may be omitted; however, all vertical-bars must be included except at the end of the line. Spaces and tabs at the end of a line are ignored.
Each line contains 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.
You may include a timestamp on each line. If ttl is nonzero (or omitted), the timestamp is a starting time for the information in the line; the line will be ignored before that time. If ttl is zero, the timestamp is an ending time (``time to die'') for the information in the line;
tinydns dynamically adjusts ttl so that the line's DNS records are not cached for more than a few seconds past the ending time. A timestamp is an external TAI64 timestamp, printed as 16 lowercase hexadecimal characters. For example, the lines
+www.heaven.af.mil|1.2.3.4|0|4000000038af1379
+www.heaven.af.mil|1.2.3.7||4000000038af1379
specify that www.heaven.af.mil will have address 1.2.3.4 until time 4000000038af1379 (2000-02-19 22:04:31 UTC) and will then switch to IP address 1.2.3.7.
A ``split-horizon'' mode is supported specifying client locations by % lines followed by the IPv4 or IPv6 compactified address together with a netprefix in CIDR notation:
%lo|ip/prefix
means that IP addresses starting with ip/prefix are in location lo. lo is a sequence of one or two ASCII letters. A client is in only one location; longer prefixes override shorter prefixes. For example,
%in|192.168./16
%ex
+jupiter.heaven.af.mil|192.168.1.2|||in
+jupiter.heaven.af.mil|1.2.3.4|||ex
specifies that jupiter.heaven.af.mil has address 192.168.1.2 for clients in the 192.168/16 subnet and address 1.2.3.4 for everyone else.
Name server for our domain fqdn.
tinydns-data creates
You may have several name servers for one domain, with a different x for each server.
Reversely, each name server x.ns.fqdn may have several (secondary) IPv4/IPv6 addresses given by additional A or AAAA records.
tinydns will return 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; in this case, tinydns-data will omit the A or AAAA record.
Name server for domain fqdn.
tinydns-data creates
If x contains a dot then it is treated specially; see above.
You may have several name servers for one domain, with a different x for each server.
Normally & is used for domains delegated by this server to child servers, while . is used for domains delegated to this server.
Host fqdn with IPv4 or IPv6 address ip depending, whether the first character is = or :.
tinydns-data creates
Remember to specify name servers for some suffix of
fqdn;
otherwise
tinydns
will not respond
to queries about
fqdn.
The same comment applies to other records described below.
Similarly, remember to specify name servers for some suffix of
d.c.b.a.in-addr.arpa
or
f.e.d....2.ip6.arpa
if that domain has been delegated to you.
Alias fqdn with IPv4 address ip in case the first character is + or an IPv6 address if ~ is supplied. This is just like =fqdn|ip|ttl except that tinydns-data does not create the PTR record.
tinydns returns addresses (from + or = or @ or . or & or : or ~ lines) in a random order in the answer section.
If there are more than 8 records, it returns a random set of 8.
Mail exchanger for fqdn.
tinydns-data creates
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 line. The line is ignored.
This type of line is used by programs that automatically edit + lines in data to temporarily exclude addresses of overloaded or dead machines. The line is ignored.
TXT record for fqdn.
tinydns-data creates
DKIM TXT record for fqdn.
tinydns-data creates
TLSA record for fqdn.
tinydns-data creates
tinydns defaults to u = 3 and s = 0, thus they don't need to be provided. The required TLSA matching type parameter is automatically calculated from the fingerprint's length.
The TLSA base domain is synthesized from the values fqdn, x, proto and port yielding a final domain name _port._proto.x.fqdn. In case those values are missing, automatically the following entry is generated: _25._tcp.mail.fqdn. However, a typical choice for x is a.mx or b.mx. If x starts with _ it is taken unaltered prepending fqdn.
PTR record for fqdn.
tinydns-data creates
CNAME record for fqdn.
tinydns-data creates
tinydns-data creates
Here, the first . is converted to @ as the contact address, ser as the serial number, ref as the refresh time, ret as the retry time, exp as the expire time, and min as the minimum time. ser, ref, ret, exp, and min may be omitted; they default to, respectively, the modification time of the data file, 16384 seconds, 2048 seconds, 1048576 seconds, and 2560 seconds.
Generic record for fqdn.
tinydns-data creates
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.
For example, the lines
+pink.floyd.u.heaven.af.mil|1.2.3.4
+*.u.heaven.af.mil|1.2.3.200
have the same effect as
+pink.floyd.u.heaven.af.mil|1.2.3.4
+joe.u.heaven.af.mil|1.2.3.200
+bill.u.heaven.af.mil|1.2.3.200
+floyd.u.heaven.af.mil|1.2.3.200
+ishtar.u.heaven.af.mil|1.2.3.200
+joe.bob.u.heaven.af.mil|1.2.3.200
+sally.floyd.u.heaven.af.mil|1.2.3.200
+post.pink.floyd.u.heaven.af.mil|1.2.3.200
=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
@heaven.af.mil|2001::25
# IPv6 declarations
:lion.heaven.af.mil|2001:fefe::123a
@heaven.af.mil|2001:fefe::25
~www.af.mil|2001:fefe::123a
=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
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.
In contrast to Felix von Leitner's implementation, IPv6 addresses are always entered in their compactified format and indicated by : (instead of '6') or ~ (instead of '3'). As a result, IPv6 addresses are not understood neither in binary nor in plain format.