tinydns-data — compile the database used by tinydns
tinydns-data
tinydns-data compiles a database in source form, in the file data
, into a compiled form, in the file data.cdb
, that is used by tinydns(1).
The compiled database in data.cdb
is a Bernstein Constant Database file.
tinydns-data updates data.cdb
atomically, building a replacement in data.cdb.tmp
and atomically renaming that replacement into place when it has completely and successfully built it it and written it to disc.
So you can use it safely while tinydns(1) is running.
The DNS information in data
is a series of lines.
It is very easy for programs to edit; and can be mainpulated with with UNIX tools such as awk(1) and sed(1).
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. Blank lines are ignored.
Many lines contain an ip
field that is an IP address.
IPv4 addresses are written in the conventional human-readable form: 192.0.2.234, 10.20.40.80
IPv6 addresses are written in the conventional human-readable form, except that (since they are field separator characters here) colons are changed to underscores and the double-colon convention is not used. All addresses must have all 8 groups: 2001_bd8_3_4_5_6_7_8, fd57_8012_f61c_0_20a2_9013_7ec4_7ab3
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:192.0.2.234:0:4000000038af1379
+www.heaven.af.mil:192.0.2.235::4000000038af1379
specify that www.heaven.af.mil
will have address 192.0.2.234 until time 4000000038af1379 (2000-02-19 22:04:31 UTC) and will then switch to IP address 192.0.2.235.
You may include a client location lo
on each line.
The line is ignored for clients outside that location.
Client locations are specified by % lines:
%lo
:ipprefix
means that IP addresses starting with ipprefix
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
%ex
+jupiter.heaven.af.mil:192.168.1.2:::in
+jupiter.heaven.af.mil:192.0.2.234:::ex
specifies that jupiter.heaven.af.mil
has address 192.168.1.2 for clients in the 192.168.* network and address 192.0.2.234 for everyone else.
comment
Comment line. The line is ignored.
fqdn
:ip
:x
:ttl
:timestamp
:lo
Apex name server for domain fqdn
.
tinydns-data creates
an NS ("name server") record showing
as a name server for x
.ns.fqdn
fqdn
;
an A ("address") record showing ip as the IP address of
; and
x
.ns.fqdn
an SOA ("start of authority") record for fqdn
listing
as the primary name server and x
.ns.fqdn
hostmaster@
as the contact address.
fqdn
You may have several name servers for one domain, with a different x
for each server.
If x
contains a dot then tinydns-data will use x
as the server name rather than
.
This feature is provided only for compatibility reasons; names not ending with x
.ns.fqdn
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 the data file; in this case, tinydns-data will omit the A record.
Examples:
.panic.mil:1.8.7.55:a
creates an NS record showing a.ns.panic.mil
as a name server for panic.mil
, an A record showing 1.8.7.55 as the IP address of a.ns.panic.mil
, and an SOA record for panic.mil
.
.panic.mil:1.8.7.56:dns2.panic.mil
creates an NS record showing dns2.panic.mil
as a name server for panic.mil
, an A record showing 1.8.7.56 as the IP address of dns2.panic.mil
, and an SOA record for panic.mil
.
.panic.mil::a.ns.heaven.af.mil
creates an NS record showing a.ns.heaven.af.mil
as a name server for panic.mil
, and an SOA record for panic.mil
.
fqdn
:ip
:x
:ttl
:timestamp
:lo
Delegation to name server for domain fqdn
.
tinydns-data creates
an NS record showing
as a name server for x
.ns.fqdn
fqdn
and
an A record showing ip
as the IP address of
.
x
.ns.fqdn
Normally & is used for domains delegated by this server to child servers, while . is used for domains delegated to this server.
You may have several name servers for one domain, with a different x
for each server.
If x
contains a dot then it is treated specially; as for . lines.
Examples:
&serious.panic.mil:1.8.248.6:a
creates an NS record showing a.ns.serious.panic.mil
as a name server for serious.panic.mil
, and an A record showing 1.8.248.6 as the IP address of a.ns.serious.panic.mil
.
&serious.panic.mil:1.8.248.7:ns7.panic.mil
creates an NS record showing ns7.panic.mil
as a name server for serious.panic.mil
, and an A record showing 1.8.248.7 as the IP address of ns7.panic.mil
.
fqdn
:ip
:ttl
:timestamp
:lo
Host fqdn
with IP address ip
.
tinydns-data creates
an A record showing ip
as the IP address of fqdn
and
a PTR ("pointer") record showing fqdn
as the name of d.c.b.a.in-addr.arpa if ip is a.b.c.d.
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, if that domain has been delegated to you.
Example:
=button.panic.mil:1.8.7.108
creates an A record showing 1.8.7.108 as the IP address of button.panic.mil
, and a PTR record showing button.panic.mil
as the name of 108.7.8.1.in-addr.arpa
.
fqdn
:ip
:ttl
:timestamp
:lo
Server side alias fqdn
with IP address ip
.
This is just like =fqdn
:ip
:ttl
except that tinydns-data does not create the PTR record.
Example:
+button.panic.mil:1.8.7.109
creates an A record showing 1.8.7.109 as another IP address for button.panic.mil
.
fqdn
:ip
:ttl
:timestamp
:lo
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.
fqdn
:ip
:x
:p
:prio
:wt
:ttl
:timestamp
:lo
Service for fqdn
.
tinydns-data creates
a SRV ("service") record showing
as a service for x
.srv.fqdn
fqdn
on port p
with priority prio
and weight wt
, and
an A record showing ip
as the IP address of
.
x
.srv.fqdn
You may omit prio
and wt
; the defaults are 0.
If x
contains a dot then it is treated specially; see above.
You may create several SRV records for fqdn
, with a different x
for each server.
Example:
S_sip._udp.panic.mil:1.8.7.88:sip.panic.mil:5060:10:20
creates a SRV record showing port 5060 of sip.panic.mil
as a SIP/UDP service for panic.mil
with priority 10 and wt 20, and an A record showing 1.8.7.88 as the IP address of sip.panic.mil
.
fqdn
:ip
:x
:dist
:ttl
:timestamp
:lo
Mail exchanger for fqdn
.
tinydns-data creates
an MX ("mail exchanger") record showing
as a mail exchanger for x
.mx.fqdn
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
.
Example:
@panic.mil:1.8.7.88:mail.panic.mil
creates an MX record showing mail.panic.mil
as a mail exchanger for panic.mil
at distance 0, and an A record showing 1.8.7.88 as the IP address of mail.panic.mil
.
fqdn
:s
:ttl
:timestamp
:lo
TXT ("text") 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
:timestamp
:lo
PTR record for fqdn
.
tinydns-data creates
a PTR record for fqdn
pointing to the domain name p
.
Usually a = line is a more convenient way to create a mapping from an IP address to a domain name.
fqdn
:p
:ttl
:timestamp
:lo
Client side alias fqdn
with target p
.
tinydns-data creates
a CNAME record for fqdn
pointing to the domain name p
.
Don't use Cfqdn
if there are any other records for fqdn
.
Don't use Cfqdn
for common aliases; use +fqdn
instead.
Remember the wise words of Inigo Montoya: "You keep using CNAME records. I do not think they mean what you think they mean."
fqdn
:mname
:rname
:ser
:ref
:ret
:exp
:min
:ttl
:timestamp
:lo
SOA record for fqdn
showing mname
as the primary name server, rname
(with the first . 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.
Usually a . line is a more convenient way to create SOA records.
fqdn
:n
:rdata
:ttl
:timestamp
:lo
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; it must not be 2 (NS), 5 (CNAME), 6 (SOA), 12 (PTR), 15 (MX), or 252 (AXFR).
The proper format of rdata
depends on n
.
You may use octal \nnn codes to include arbitrary bytes inside rdata
.
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