.TH tinydns-data 8

.SH NAME
tinydns-data \- data tool for tinydns

.SH DESCRIPTION
This is a reference page.
For tutorial information, see the instructions for
.br
.B running a DNS server
(http://cr.yp.to/djbdns/run-server.html).

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

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

.SH Data format
The DNS information in 
.I 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.
Blank lines are ignored.

Each line contains a
.I 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
.IR ttl ;
.B tinydns-data
will use default cache times,
carefully selected to work well in normal situations.

You may include a timestamp on each line.
If
.I 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 
.I ttl
is zero,
the timestamp is an ending time (``time to die'')
for the information in the line;
.BR tinydns (8)
dynamically adjusts 
.I 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 
.I www.heaven.af.mil
will have address 
.I 1.2.3.4
until time 
.I 4000000038af1379
(2000-02-19 22:04:31 UTC)
and will then switch to IP address 
.IR 1.2.3.7 .

For versions 1.04 and above:
You may include a client location on each line.
The line is ignored for clients outside that location.
Client locations are specified by
.B %
lines:

%\fIlo\fR:\fIipprefix\fR

means that IP addresses starting with
.I ipprefix
are in location
.IR lo .
.I 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:1.2.3.4:::ex

specifies that
.I jupiter.heaven.af.mil
has address
.I 192.168.1.2
for clients in the
.I 192.168.*
network
and address
.I 1.2.3.4
for everyone else.

.SH Common data lines

.RI \. fqdn\fR:\fIip\fR:\fIx\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR

Name server for our domain 
.IR fqdn .

.B tinydns-data
creates
.IP
an NS (``name server'') record
showing 
.IR x .ns.\fIfqdn\fR
as a name server for
.IR fqdn ;
.P
.IP
an A (``address'') record showing
.I ip
as the IP address
of
.IR x\fR.ns.\fIfqdn ;
and
.P
.IP
an SOA (``start of authority'') record for 
.I fqdn
listing 
.IR x\fR.ns.\fIfqdn
as the primary name server
and hostmaster@\fIfqdn\fR
as the contact address.
.P

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

.BR tinydns (8)
will return only one SOA record per domain.

If
.I x
contains a dot
then 
.B tinydns-data
will use 
.I x
as the server name
rather than 
.IR x\fR.ns.\fIfqdn .
This feature is provided only for compatibility reasons;
names not ending with
.I 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 
.I ip
if 
.I x
has IP addresses assigned elsewhere in 
.IR data ;
in this case,
.B tinydns-data
will omit the A record.
.P
Examples:

  .panic.mil:1.8.7.55:a

creates an NS record showing
.I a.ns.panic.mil
as a name server for
.IR panic.mil ,
an A record showing
.I 1.8.7.55
as the IP address of
.IR a.ns.panic.mil ,
and an SOA record for
.IR panic.mil .

  .panic.mil:1.8.7.56:dns2.panic.mil

creates an NS record showing
.I dns2.panic.mil
as a name server for
.IR panic.mil ,
an A record showing
.I 1.8.7.56
as the IP address of
.IR dns2.panic.mil ,
and an SOA record for
.IR panic.mil .

  .panic.mil::a.ns.heaven.af.mil

creates an NS record showing
.I a.ns.heaven.af.mil
as a name server for
.IR panic.mil ,
and an SOA record for
.IR panic.mil .

.RI & fqdn\fR:\fIip\fR:\fIx\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR

Name server for domain
.IR fqdn .

.B tinydns-data
creates
.IP
an NS record
showing 
.IR x\fR.ns.\fIfqdn
as a name server for 
.IR fqdn
and
.P
.IP
an A record showing
.I ip
as the IP address
of
.IR x\fR.ns.\fIfqdn .
.P

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

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

Normally
.I &
is used
for domains delegated by this server to child servers,
while
.I .
is used for domains delegated to this server.
.P
Examples:

  &serious.panic.mil:1.8.248.6:a

creates an NS record showing
.I a.ns.serious.panic.mil
as a name server for
.IR serious.panic.mil ,
and an A record showing
.I 1.8.248.6
as the IP address of
.IR a.ns.serious.panic.mil .

  &serious.panic.mil:1.8.248.7:ns7.panic.mil

creates an NS record showing
.I ns7.panic.mil
as a name server for
.IR serious.panic.mil ,
and an A record showing
.I 1.8.248.7
as the IP address of
.IR ns7.panic.mil .

.RI = fqdn\fR:\fIip\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR

Host
.I fqdn
with IP address 
.IR ip .

.B tinydns-data
creates
.IP
an A record showing 
.I ip
as
the IP address of 
.IR fqdn
and
.P
.IP
a PTR (``pointer'') record showing 
.I fqdn
as
the name of 
.IR d.c.b.a .in-addr.arpa
if 
.I ip
is 
.IR a.b.c.d .
.P

Remember to specify name servers for some suffix of
.IR fqdn ;
otherwise 
.BR tinydns (8)
will not respond
to queries about
.IR fqdn .
The same comment applies to other records described below.
Similarly, remember to specify name servers for some suffix of
.IR d.c.b.a .in-addr.arpa,
if that domain has been delegated to you.
.P
Example:

  =button.panic.mil:1.8.7.108

creates an A record showing
.I 1.8.7.108
as the IP address of
.IR button.panic.mil ,
and a PTR record showing
.I button.panic.mil
as the name of
.IR 108.7.8.1.in-addr.arpa .

.RI + fqdn\fR:\fIip\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR

Alias
.I fqdn
with IP address 
.IR ip .
This is just like 
.RI = fqdn\fR:\fIip\fR:\fIttl\fR
except that 
.B tinydns-data
does not create the PTR record.

For versions 1.04 and above:
.BR tinydns (8)
returns addresses
(from
.I +
or
.I =
or
.I @
or
.I .
or
.I &
lines)
in a random order in the answer section.
If there are more than 8 records,
it returns a random set of 8.
.P
Example:

  +button.panic.mil:1.8.7.109

creates an A record showing
.I 1.8.7.109
as another IP address for
.IR button.panic.mil .

.RI @ fqdn\fR:\fIip\fR:\fIx\fR:\fIdist\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR

Mail exchanger for 
.IR fqdn .

.B tinydns-data
creates
.IP
an MX (``mail exchanger'') record
showing 
.IR x\fR.mx.\fIfqdn
as a mail exchanger for 
.I fqdn
at distance 
.I dist
and
.P
.IP
an A record showing 
.I ip
as the IP address
of 
.IR x\fR.mx.\fIfqdn .
.P
You may omit 
.IR dist ;
the default distance is 0.

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

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

  @panic.mil:1.8.7.88:mail.panic.mil

creates an MX record showing
.I mail.panic.mil
as a mail exchanger for
.I panic.mil
at distance 0, and an A record showing
.I 1.8.7.88
as the IP address of
.IR mail.panic.mil .

.RI # comment

Comment line. The line is ignored.

.SH Uncommon data lines

.RI - fqdn\fR:\fIs\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR

For versions 1.04 and above:
This type of line is used by
programs that automatically edit
.B +
lines in
.I data
to temporarily exclude addresses of overloaded or dead machines.
The line is ignored.

.RI ' fqdn\fR:\fIs\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR

TXT (``text'') record for 
.IR fqdn .
.B tinydns-data
creates a TXT record for 
.I fqdn
containing the string 
.IR s .
You may use octal 
.RI \ nnn
codes
to include arbitrary bytes inside 
.IR s ;
for example, 
.RI \ 072
is a colon.

.RI ^ fqdn\fR:\fIp\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR

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

.RI C fqdn\fR:\fIp\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR

CNAME (``canonical name'') record for 
.IR fqdn .
.B tinydns-data
creates a CNAME record for 
.I fqdn
pointing to the domain name 
.IR p .

Don't use
.RI C fqdn
if there are any other records for
.I fqdn
Don't use
.RI C fqdn
for common aliases;
use
.RI + 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.''

.RI Z fqdn\fR:\fImname\fR:\fIrname\fR:\fIser\fR:\fIref\fR:\fIret\fR:\fIexp\fR:\fImin\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR

SOA record for 
.I fqdn
showing 
.I mname
as the primary name server,
.I rname
(with the first 
.I .
converted to 
.IR @ )
as the contact address,
.I ser
as the serial number,
.I ref
as the refresh time,
.I ret
as the retry time,
.I exp
as the expire time, and
.I min
as the minimum time.
.IR ser ,
.IR ref ,
.IR ret ,
.IR exp ,
and
.I min
may be omitted;
they default to, respectively,
the modification time of the 
.I data
file,
16384 seconds,
2048 seconds,
1048576 seconds, and
2560 seconds.

.RI : fqdn\fR:\fIn\fR:\fIrdata\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR

Generic record for
.IR fqdn .
.B tinydns-data
creates a record of type 
.I n
for 
.I fqdn
showing 
.IR rdata .
.I 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
.I rdata
depends on 
.IR n .
You may use octal 
.RI \ nnn
codes
to include arbitrary bytes inside 
.IR rdata .

.SH Wildcards

.I tinydns
supports wildcards of the form 
.IR *.fqdn .
Information for 
.I *.fqdn
is provided for every name ending with 
.IR .fqdn ,
.I except
names that have their own records
and names that are covered by more specific wildcards.

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

and so on.

As another example, the lines

  +pink.floyd.u.heaven.af.mil:1.2.3.4
  @*.u.heaven.af.mil::mail.heaven.af.mil

have the same effect as

  +pink.floyd.u.heaven.af.mil:1.2.3.4
  @joe.u.heaven.af.mil::mail.heaven.af.mil
  @bill.u.heaven.af.mil::mail.heaven.af.mil
  @floyd.u.heaven.af.mil::mail.heaven.af.mil
  @ishtar.u.heaven.af.mil::mail.heaven.af.mil
  @joe.bob.u.heaven.af.mil::mail.heaven.af.mil
  @sally.floyd.u.heaven.af.mil::mail.heaven.af.mil
  @post.pink.floyd.u.heaven.af.mil::mail.heaven.af.mil

and so on.
Notice that the wildcard does not apply to
.IR pink.floyd.u.heaven.af.mil ,
because that name has its own records.

.SH 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 BIND 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

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

.B 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.

.SH SEE ALSO
tinydns(8)

http://cr.yp.to/djbdns.html