tinydns-data(8)

📦
version 1.05 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

tinydns-data — the data tool for tinydns ✨ (like, it feeds your whole DNS server, ngl)

🌸 DESCRIPTION 🌸

okay so bestie, quick heads up before anything else: this is a reference page, not a tutorial. If you want the hand-holding walkthrough, go read the instructions for running a DNS server over at http://cr.yp.to/djbdns/run-server.html 🫶

tinydns-data reads your local DNS info out of a file literally named data sitting in the current directory. Then it builds data.cdb in a binary format specially designed so tinydns(8) can access it fast. It may also create some other files whose names begin with data 💅

And here's the iconic part: tinydns-data updates data.cdb atomically, so you can run it safely while tinydns(8) is still up and running. No drama, no downtime, we love to see it 😌 If anything goes wrong while creating data.cdb, tinydns-data just stops and leaves the old data.cdb exactly where it was. Old faithful stays safe. 👑

📋 Data format 📋

The DNS info inside data is just a series of lines, and there are several types of lines (we'll get to all of them, don't worry). 🦋

Every line starts with a special character and then continues with a series of colon-separated fields. In some cases you can skip fields — but ⚠️ all the colons must still be there, except at the end of the line. Spaces and tabs at the end of a line? Ignored. Blank lines? Also ignored. Zero thoughts, no notes. 💀

Each line carries a ttl (that's "time to live") saying how many seconds that line's DNS records are allowed to be cached. Big warning though: cache times under 300 seconds get treated as 300 by some clients, and NS cache times under 2 seconds can cause lookup failures. 😭 You're allowed to omit ttl entirely — tinydns-data will pick default cache times that were carefully chosen to work well in normal situations. Trust the defaults, they ate. ✨

You can also put a timestamp on each line. Here's how that works:

  • If ttl is nonzero (or omitted), the timestamp is a starting time for the info on the line — the line is ignored before that moment. ⏳
  • If ttl is zero, the timestamp is an ending time (a "time to die" 🪦) for the info on the line; tinydns(8) dynamically adjusts ttl so the line's DNS records aren't cached for more than a few seconds past that ending time.

A timestamp is an external TAI64 timestamp, printed as 16 lowercase hexadecimal characters. For example, these lines:

+www.heaven.af.mil:1.2.3.4:0:4000000038af1379
+www.heaven.af.mil:1.2.3.7::4000000038af1379

say that www.heaven.af.mil will have address 1.2.3.4 until time 4000000038af1379 (that's 2000-02-19 22:04:31 UTC) and will then switch to IP address 1.2.3.7. The glow-up is scheduled. 🦋

For versions 1.04 and above: you can also put a client location on each line. The line then gets ignored for clients outside that location. Client locations are declared with % lines:

%lo:ipprefix

means IP addresses starting with ipprefix are in location lo. And lo is a sequence of one or two ASCII letters. A client lives in exactly one location — longer prefixes override shorter prefixes. No double-dipping. 🙅‍♀️ 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 jupiter.heaven.af.mil has address 192.168.1.2 for clients in the 192.168.* network and address 1.2.3.4 for everyone else. Two addresses, two audiences, one icon. 👑

👑 Common data lines 👑

.fqdn:ip:x:ttl:timestamp:lo

Name server for our domain fqdn. 💖

tinydns-data creates:

  • an NS ("name server") record showing x.ns.fqdn as a name server for fqdn;
  • an A ("address") record showing ip as the IP 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 can have several name servers for one domain, with a different x for each server. And heads up: tinydns(8) will return only one SOA record per domain.

If x contains a dot, then tinydns-data uses x as the server name instead of x.ns.fqdn. ⚠️ This feature exists 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. So like, don't, bestie. 🙈 You should omit ip if x has IP addresses assigned elsewhere in data; in that 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

Name server for domain fqdn.

tinydns-data creates:

  • an NS record showing x.ns.fqdn as a name server for fqdn and
  • an A record showing ip as the IP address of x.ns.fqdn.

If x contains a dot then it's treated specially — see above, same energy. 👆

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. Two different jobs, two different glyphs, don't mix them up. 💅

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(8) will not respond to queries about fqdn. 😭 The same comment applies to the 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. Reverse lookup, but make it cute. 🎀

+fqdn:ip:ttl:timestamp:lo

Alias fqdn with IP address ip. This is just like =fqdn:ip:ttl except that tinydns-data does not create the PTR record. Same recipe, minus one ingredient. ✨

For versions 1.04 and above: tinydns(8) returns addresses (from + or = or @ or . or & lines) in a random order in the answer section. And if there are more than 8 records, it returns a random set of 8. Shuffle mode: activated. 🔀

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: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 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's treated specially — see above. 👆

You may create several MX records for fqdn, with a different x for each server. And please, 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.

#comment

Comment line. The line is ignored. Yes bestie, it's giving nothing and that's the point. 💅

🦋 Uncommon data lines 🦋

-fqdn:s:ttl:timestamp:lo

For versions 1.04 and above: 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. 🪦 (temporarily benched, not deleted)

'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. Sneaky but valid. 😌

^fqdn:p:ttl:timestamp:lo

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

Cfqdn:p:ttl:timestamp:lo

CNAME ("canonical name") record for fqdn. 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.

And remember the wise words of Inigo Montoya: "You keep using CNAME records. I do not think they mean what you think they mean." 🗡️ iconic, honestly.

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. ✨ (defaults really said "we got you")

: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). 🚫 Those are taken, babe.

The proper format of rdata depends on n. You may use octal \nnn codes to include arbitrary bytes inside rdata. 🦋

🦋 WILDCARDS 🦋

okay bestie, this is the part that makes everyone go feral: tinydns supports wildcards of the form *.fqdn. ✨

so the way it works is: info for *.fqdn gets handed out for every name that ends with .fqdn — except names that have their own records, and names that are already covered by more specific wildcards. no cap. 💅

for example, these lines:

+pink.floyd.u.heaven.af.mil:1.2.3.4
+*.u.heaven.af.mil:1.2.3.200

have the exact 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. 👑

heads up tho: notice that the wildcard does not apply to pink.floyd.u.heaven.af.mil, because that name has its own records. the specific one always wins. it's giving main character energy and honestly? deserved. 💅

🌸 A TYPICAL DATA FILE 🌸

like, this is what an actual one looks like:

=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

look at that. two whole formats. same vibes. slay. 🌈

✨ DESIGN NOTES ✨

so the whole reason this format exists: it's very easy for programs to edit, and reasonably easy for humans to edit — unlike the traditional zone-file format. 🫶

and a lil thought experiment for you: 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. that would reliably track changes in offsite IP addresses if the database were rebuilt periodically. (it doesn't do that. it's just a note. iykyk. 💭)

👀 SEE ALSO 👀

and that's the whole page, bestie!! you made it to the end 🎉 this was tinydns-data(8), from the djbdns source, dated like all the classic manpages of that era — go forth and populate your data file with confidence. mwah 💖

📦 where this page comes from