tinydns-data 1 user commands djbwares
tinydns-data compile the database used by tinydns
`tinydns-data`

## Description

`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, a write-once read-many binary file that provides much faster lookups than repeatedly parsing text files at runtime.

The compiled database will change in a non-backwards-compatible way when tinydns 1 and axfrdns 1 support IPv6 client locations in a future release.

`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 expected workflow is to run `tinydns-data` every time that a change is made to `data`, tracking this with a utility such as make 1. For similar mechanisms elsewhere, compare pwd_mkdb 1 for compiling the master.passwd 5 file into a Berkeley DB file, and cap_mkdb 1 for compiling various files such as login.conf 5.

## Data format

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 is also a tinydns-edit 1 tool for performing several common modifications, which handles updating the source `data` file itself atomically (something that otherwise needs to be done explicitly with the general-purpose text processing tools).

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.

### IP addresses

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

### Timestamps and scheduled changes

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.example:192.0.2.234:0:4000000038af1379
    +www.heaven.af.example:192.0.2.235::4000000038af1379

specify that `www.heaven.af.example` 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.

### Client locations

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.example:192.168.1.2:::in
    +jupiter.heaven.af.example:192.0.2.234:::ex
    +jupiter.heaven.af.example:3fff_0_1977_0905_1979_0305_1_2:::ex

specifies that `jupiter.heaven.af.example` has address 192.168.1.2 for clients in the 192.168.* network and addresses 192.0.2.234 and 3fff:0:1977:905:1979:305:1:2 for everyone else.

### Line types

    #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 `x.ns.fqdn` as a name server for fqdn;

  - an A or AAAA ("address") record showing ip as the IP (4 or 6, respectively) address of `x.ns.fqdn`; and

  - an SOA ("start of authority") record for fqdn listing `x.ns.fqdn` as the primary name server and `hostmaster@fqdn` as the contact address.

  You may have several name servers for one domain, with a different x for each server. 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.

  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. The better `x.ns.fqdn` scheme, where x is a single letter, is designed to use in-bailiwick delegation and to take maximum advantage of the noddy compression scheme used by the DNS protocol so that as much of a large multi-nameserver delegation as possible can fit into a 512-octet DNS/UDP packet.

  #### Examples

      .panic.example:203.0.113.55:a
      .panic.example:3fff_0_1978_0308_1980_0125_0102_55:a

  creates an NS record showing `a.ns.panic.example` as a name server for `panic.example`, an A record showing 203.0.113.55 as the IPv4 address of `a.ns.panic.example`, an AAAA record showing 3fff:0:1978:308:1980:125:102:55 as the IPv6 address of `a.ns.panic.example`, and an SOA record for `panic.example`.

      .panic.example:203.0.113.56:dns2.panic.example
      .panic.example:3fff_0_1978_0308_1980_0125_0102_56:dns2.panic.example

  creates an NS record showing `dns2.panic.example` as a name server for `panic.example`, an A record showing 203.0.113.56 as the IPv4 address of `dns2.panic.example`, an AAAA record showing 3fff:0:1978:308:1980:125:102:56 as the IPv6 address of `dns2.panic.example`, and an SOA record for `panic.example`.

      .panic.example::a.ns.heaven.af.example

  creates an NS record showing `a.ns.heaven.af.example` as a name server for `panic.example`, and an SOA record for `panic.example`.

    &fqdn:ip:x:ttl:timestamp:lo

  Delegation to name server for domain fqdn. `tinydns-data` creates

  - an NS record showing `x.ns.fqdn` as a name server for fqdn and

  - an A or AAAA 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 by other servers 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 and with the same caveat.

  #### Examples

      &serious.panic.example:203.0.113.6:a
      &serious.panic.example:3fff_0_1978_0308_1980_0125_0102_6:a

  creates an NS record showing `a.ns.serious.panic.example` as a name server for `serious.panic.example`, an A record showing 203.0.113.6 as the IPv4 address of `a.ns.serious.panic.example`, and an AAAA record showing 3fff:0:1978:308:1980:125:102:6 as the IPv6 address of `a.ns.serious.panic.example`.

      &serious.panic.example:203.0.113.7:ns7.panic.example
      &serious.panic.example:3fff_0_1978_0308_1980_0125_0102_7:ns7.panic.example

  creates an NS record showing `ns7.panic.example` as a name server for `serious.panic.example`, an A record showing 203.0.113.7 as the IPv4 address of `ns7.panic.example`, and an AAAA record showing 3fff:0:1978:308:1980:125:102:7 as the IPv6 address of `ns7.panic.example`.

    =fqdn:ip:ttl:timestamp:lo

  Host fqdn with IP address ip. `tinydns-data` creates

  - an A or AAAA 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

      =dont.panic.example:203.0.113.108
      =dont.panic.example:3fff_0_1978_0308_1980_0125_0102_108

  creates an A record showing 203.0.113.108 as the IPv4 address of `dont.panic.example`, an AAAA record showing 3fff:0:1978:308:1980:125:102:108 as the IPv6 address of `dont.panic.example`, and PTR records showing `dont.panic.example` as the names of `108.113.0.203.in-addr.arpa` and `8.0.1.0.2.0.1.0.5.2.1.0.0.8.9.1.8.0.3.0.8.7.9.1.0.0.0.0.f.f.f.3.ip6.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

      +dont.panic.example:203.0.113.109
      +dont.panic.example:3fff_0_1978_0308_1980_0125_0102_109

  creates an A record showing 203.0.113.109 as another IPv4 address for `dont.panic.example`, and an AAAA record showing 3fff:0:1978:308:1980:125:102:109 as another IPv6 address for `dont.panic.example`.

    -fqdn:ip:ttl:timestamp:lo

  This type of line is used by programs that automatically edit `+` lines in data to temporarily exclude addresses of machines whilst leaving the possibility for simply restoring them. (A machine, or one of its network interfaces, could be temporarily out of service, for example.) The line is ignored.

  #### Example

      -dont.panic.example:203.0.113.109
      +dont.panic.example:3fff_0_1978_0308_1980_0125_0102_109

  is how the IPv4 address record can be disabled from the `+` example.

    Sfqdn:ip:x:p:prio:wt:ttl:timestamp:lo

  Service for fqdn. `tinydns-data` creates

  - a SRV ("service") record showing `x.srv.fqdn` as a service for fqdn on port p with priority prio and weight wt, and

  - an A or AAAA 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.

  The `x.srv.fqdn` names may seem cumbersome to humans, but the idea of service records is that humans do not see these domain names. They see a program that (say) speaks SIP over TCP, and only the part of fqdn after the initial underscored labels. The `x.srv` scheme, moreover, has the same compression advantages for DNS/UDP packets as for `.`, `&`, and `@` lines.

  #### Examples

      S_sip._udp.slocombe.example:203.0.113.88:a:5060:10:20
      S_sip._udp.slocombe.example:3fff_0_1972_0908_1985_0401_33_88:a:5060:10:20

  creates a SRV record showing port 5060 of `a.srv._sip._udp.slocombe.example` as a SIP/UDP service for `slocombe.example` with priority 10 and wt 20, an A record showing 203.0.113.88 as the IPv4 address of `a.srv._sip._udp.slocombe.example`, and an AAAA record showing 3fff:0:1972:908:1985:401:33:88 as the IPv6 address of `a.srv._sip._udp.slocombe.example`.

      S_nicname._tcp.humphries.example:203.0.113.65:a:43:10:20
      S_nicname._tcp.humphries.example:3fff_0_1972_0908_1985_0401_33_65:a:43:10:20

  creates a SRV record showing port 43 of `a.srv._nicname._tcp.humphries.example` as a NICNAME/TCP service for `humphries.example` with priority 10 and wt 20, an A record showing 203.0.113.65 as the IPv4 address of `a.srv._nicname._tcp.humphries.example`, and an AAAA record showing 3fff:0:1972:908:1985:401:33:65 as the IPv6 address of `a.srv._nicname._tcp.humphries.example`.

      S_gemini._tcp.brahms.example:203.0.113.45:a:1965:10:20
      S_gemini._tcp.brahms.example:3fff_0_1972_0908_1985_0401_33_45:a:1965:10:20

  creates a SRV record showing port 1965 of `a.srv._gemini._tcp.brahms.example` as a GEMINI/TCP service for `brahms.example` with priority 10 and wt 20, an A record showing 203.0.113.45 as the IPv4 address of `a.srv._gemini._tcp.brahms.example`, and an AAAA record showing 3fff:0:1972:908:1985:401:33:45 as the IPv6 address of `a.srv._gemini._tcp.brahms.example`.

    Hfqdn:ip:x:prio:params:ttl:timestamp:lo

  HTTPS service for fqdn. `tinydns-data` creates

  - an HTTPS ("HTTP/SSL service") record showing `x.fqdn` as an HTTPS service for fqdn with priority prio, and

  - an A or AAAA record showing ip as the IP address of `x.fqdn`.

  params is not currently implemented and must be blank.

  You may omit prio; the default is 0. If x contains a dot then it is treated specially; see above. If x is omitted then it defaults to `.`. You may create several HTTPS records for fqdn, with a different x for each server.

  #### Examples

      Hrumbold.example:203.0.113.88:a:0
      Hrumbold.example:3fff_0_1972_0908_1985_0401_33_88:a:0

  creates an HTTPS record showing `a.rumbold.example` as an HTTPS service for `rumbold.example` with priority 0, an A record showing 203.0.113.88 as the IPv4 address of `a.rumbold.example`, and an AAAA record showing 3fff:0:1972:908:1985:401:33:88 as the IPv6 address of `a.rumbold.example`.

    @fqdn:ip:x:dist:ttl:timestamp:lo

  Mail exchanger for fqdn. `tinydns-data` creates

  - an MX ("mail exchanger") record showing `x.mx.fqdn` as a mail exchanger for fqdn at distance dist and

  - an A or AAAA 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.example:203.0.113.88:a
      @panic.example:3fff_0_1978_0308_1980_0125_0102_88:a

  creates an MX record showing `a.mx.panic.example` as a mail exchanger for `panic.example` at distance 0, an A record showing 203.0.113.88 as the IP address of `a.mx.panic.example`, and an AAAA record showing 3fff:0:1978:308:1980:125:102:88 as the IP address of `a.mx.panic.example`.

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

    Cfqdn: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. The DNS protocol does not handle this. Don't use `Cfqdn` for straightforward simple aliases all mapping fqdns to a common IP address; use `+fqdn` instead. The latter is a lot more efficient, as it is handled DNS server-side rather than DNS client-side. Remember the wise words of Inigo Montoya: "You keep using CNAME records. I do not think they mean what you think they mean."

    Zfqdn: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), 251 (IXFR), 252 (AXFR) or 255 (ANY). The proper format of rdata depends on n. You may use octal \nnn codes to include arbitrary bytes inside rdata.

## Example

A typical data file:

    .heaven.af.example:203.0.113.5:a
    .heaven.af.example:203.0.113.6:b
    .heaven.af.example:3fff_0_4ab1_7_eb53_6820_90_5:a
    .heaven.af.example:3fff_0_4ab1_7_eb53_6820_90_6:b
    # per support contract, renewable annually -- jim
    .heaven.af.example:3fff_0_8_716d_bac8_92_322_53:a.ns.offsite.example.com

    .113.0.203.in-addr.arpa:203.0.113.5:a
    .113.0.203.in-addr.arpa:203.0.113.6:b
    .0.f.f.f.3.ip6.arpa:3fff_0_4ab1_7_eb53_6820_90_5:a
    .0.f.f.f.3.ip6.arpa:3fff_0_4ab1_7_eb53_6820_90_6:b

    @heaven.af.example:203.0.113.4:a:10
    @heaven.af.example::offsite.example.com:20

    =lion.heaven.af.example:203.0.113.4
    +lion.heaven.af.example:3fff_0_4ab1_7_eb53_6820_90_4:b
    =tiger.heaven.af.example:3fff_0_4ab1_7_eb53_6820_90_5:b
    +tiger.heaven.af.example:203.0.113.5
    =bear.heaven.af.example:203.0.113.6
    +bear.heaven.af.example:3fff_0_4ab1_7_eb53_6820_90_6:b
    # cheetah's IPv6 is wonky -- jim
    =cheetah.heaven.af.example:203.0.113.248
    -cheetah.heaven.af.example:3fff_0_4ab1_7_eb53_6820_90_248:b
    # experiment with IPv6-only for panther -- jim
    =panther.heaven.af.example:3fff_0_4ab1_7_eb53_6820_90_249:b
    -panther.heaven.af.example:203.0.113.249

## History

`tinydns-data` was originally part of Daniel J. Bernstein's djbdns toolset in 2000.

`tinydns-data` ceased using the `ip6.int.` superdomain in 2016. The `ip6.int.` superdomain was deprecated by RFC3152 in 2001 and obsoleted by RFC4159 in 2005.

## Author

Original code and documentation by Daniel J. Bernstein. Documentation modernizations by Jonathan de Boyne Pollard.