TinyDNS Format

Contents

“TinyDNS is a DNS server which accepts iterative DNS queries from hosts around the Internet, and responds with locally configured information.” – D. J. Bernstein

How to Publish DNS Records Through Bytemark

To publish DNS records through Bytemark, you need to do the following:

Create a TinyDNS format file containing your DNS records.
Upload them to our upload server, as described in Content DNS service
Check that we’ve published the records. For example with host example.com a.ns.bytemark.co.uk or dig +short example.com @a.ns.bytemark.co.uk
Make sure your Domain registration is using our DNS servers. If we host your Domain, then go to https://panel.bytemark.co.uk/domains, find the domain, and click on “registrar tools”. From there, find “Manage Name Servers”. Don’t do this til we’ve published the records.

TinyDNS files

You can give the file any name you like, but DOMAINNAME.txt (e.g. “example.com.txt” for the domain example.com), is recommended. That’s what Symbiosis will do, for example.

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. So, each line looks like this:x:fqdn:DATA:ttl:timestamp:locationUsually timestamp and location are omitted, and ttl is 300, so you’ll more often see something like x:fqdn:DATA:300, where DATA may be one or more fields.

External documentation

D. J. Bernstein invented TinyDNS as a machine editable format. His documentation is at https://cr.yp.to/djbdns/tinydns-data.html It doesn’t cover IPv6, though our implementation does support IPv6. It doesn’t cover DNSSEC, and we don’t support DNSSEC. We are aware that there’s a DNSSEC extension available.

TinyDNS line formats

Special characters

These are the most common line formats. Note that some lines result in the publication of two or three DNS records, for example, and “A” record and a corresponding “PTR” record.

# hash: a comment, these lines are ignored – no DNS entry is created
.fqdn:IP:X:ttl:timestamp:lo: “common data” lines, which will publish SOA, NS and optionally A records (for the name servers). X is the name of one of your name servers. IP is for an IP address, but should be empty if there’s already an A record for that name server. Leave IP empty if you’re using our name servers. Don’t use this for delegation, use & instead. See the example below.
&fqdn:ip:x:ttl:timestamp:lo: Delegation records. Will publish an NS (name server) record pointing to x. Also an A record if ‘ip’ is not empty. Will not publish an SOA record. Use this for delegating a subdomain to another server
+fqdn:ip:ttl:timestamp:lo: publishes an A record
=fqdn:ip:ttl:timestamp:lo: an A record and the corresponding PTR record. If you don’t have authority to publish PTR records, we’ll just publish the A record. Use + in preference, unless you know we’ve delegated authority for your IP address.
3fqdn:ip:ttl:timestamp:lo: an AAAA record
6fqdn:ip:ttl:timestamp:lo: an AAAA record and the corresponding PTR record. If you don’t have authority to publish PTR records, we’ll just publish the A record. Use + in preference, unless you know we’ve delegated authority for your IP address.
@fqdn:ip:x:dist:ttl:timestamp:lo: an MX record (which must resolve to a domain name, not an IP address). “dist” is the priority of the record.
‘fqdn:s:ttl:timestamp:lo: a TXT record. Including for SPF and DKIM. “s” is a text string. Colons should be escaped as “\072”
Cfqdn:p:ttl:timestamp:lo: a CNAME record. p is a target fully qualified domain name.
Sfqdn:ip:x:port:priority:weight:ttl:timestamp:lo: An SRV record. ip can be left empty. x is the target host name. port is required, priority and weight default to zero, which is fine if you have only one target, or have no preference as to the order in which your targets are tried.
:fqdn:n:rdata:ttl:timestamp:lo: a generic record type, where “n” is the record type, and “rdata” is the date you want to publish there.

FQDNs

A fully qualified domain name is the full name. You can’t assume that your domain name will be appended. So, don’t ever write “foo” when you mean “foo.example.com”. You can sometimes write “*.example.com” to mean any subdomain of example.com, except anything that has a more specific definition. You can use any FQDN, even if you don’t own the domain, but it shouldn’t have any effect.

IPv6 addresses

There are various ways of compressing IPv6 records, by removing leading zeros, and using “::” (just once) to omit a variable number of empty fields.

TinyDNS likes an uncompressed format without colon separators, like “fe80000000000000080aba55a2dca1b6” rather than “fe80::80a:ba55:a2dc:a1b6”. If you install ipv6calc (with apt-get install ipv6calc), you can use it to do the translation like this: ipv6calc –printfulluncompressed fe80::80a:ba55:a2dc:a1b6|tr -d :, using “tr” to strip the colons.

Data fields

After the special character and FQDN follow some data fields. See above for details. After the data fields come some meta-data fields: ttl, timestamp, and location.

TTL

Most lines in the examples below end “:300”. 300 is a Time To Live (TTL) which is advice on how long a client should cache lookups. Here, it’s 300 seconds. That means that any changes should propogate throughout the DNS system inside five minutes. In practice, some clients will cache for longer: perhaps for 24 hours, for example.

Timestamp

The timestamp field is useful if you’d like to change a record at some quiet time in the future, like 2am on Sunday. Duplicate the record. Append a timestamp to one record. Make the TTL zero on the second copy, and append the same timestamp. Like this:

## before
+mx.example.com:127.0.0.1:0:400000005AA48DA0
## after
+mx.example.com:127.0.0.2:300:400000005AA48DA0

How do I calculate the timestamp? It’s a TAI64 format time stamp, which is long enough to support any time to the nearest second for the entire history of the universe. We hope that suffices! If you have Debian operating system (or probably other Linux distros), then install the “bc” package, and run something like this:

echo "obase=16;" `date +%s --date="2am next sunday"` "+ 2^62"|bc

Location

The TinyDNS format allows you to publish a location field, so you can publish different results to different clients. But we throw away the location field. You can write it, if you like, I think, but it won’t be published, so it will have no effect.

Examples

Symbiosis will create TinyDNS format files, and upload them to our server for you. So, you can use Symbiosis to generate examples that you can work from without modifying your live DNS records. You could, for example, publish records for a subdomain of your main domain (like dnstest.example.com). The following is standard Symbiosis 8, with the addition of DKIM, DMARC, and SPF records as described in the Symbiosis Documentation

#  Nameserver records.
#
### these lines declare the DNS servers for the domain, with NS records, and publish an SOA record
### the empty field ('::') could contain an IP address for an 'A' record for the name server, but we publish those elsewhere, so you should not.
.example.com::a.ns.bytemark.co.uk:300
.example.com::b.ns.bytemark.co.uk:300
.example.com::c.ns.bytemark.co.uk:300

#
#  The domain name itself
#
### lines beginning '=' publish an 'A' record and a corresponding 'PTR' record
=example.com:46.43.0.15:300

#
#  Useful aliases.
#
### lines beginning with '+' just publish the 'A' record.
+ftp.example.com:46.43.0.15:300
+www.example.com:46.43.0.15:300
+mail.example.com:46.43.0.15:300

#
# A record for MX
#
+mx.example.com:46.43.0.15:300

#
#  The domain name itself -- AAAA record and reverse.
#
### lines beginning with '6' publish an 'AAAA' record, and corresponding 'PTR' record
6example.com:200141c90001041d0000000000000015:300

#
#  Useful aliases -- AAAA records only
#
### lines beginning with a '3' pubish an 'AAAA' record only
3ftp.example.com:200141c90001041d0000000000000015:300
3www.example.com:200141c90001041d0000000000000015:300
3mail.example.com:200141c90001041d0000000000000015:300

#
# AAAA record for MX
#
3mx.example.com:200141c90001041d0000000000000015:300

#
# MX record -- no IP defined, as this is done separately above.
#
### lines beginning with '@' publish an MX record
@example.com::mx.example.com:15:300
#
# SPF records
#
### lines starting with "'" are TXT records
### SPF records are just TXT records. There is an SPF record type, but it's deprecated and we don't use it
'example.com:v=spf1 +a +mx ?all:300

#
# DKIM records
#
### DKIM records are also TXT records, containing a public key
'blah._domainkey.example.com:v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6OFbTTD2lHK8cyHCrMRb6+ZuzaSX+lNEyH0IsIF0fj1XbxANY/JUGqV5DOszyJeAvBEMm9G1mXjaUTFt9xvh0ByNLHdyCbcgsMZp7USi0v7JnuMuGrKdTslx2kCUkjYj6D81n/GKFkIvlu9/YMlVW3+ezZ5W9pnyaogCvslMR9PeU4ldSdoAxuKU5V7c37LQNNjrI2snAicvOsFpheih+en5gaFYU1uytq3SZyR2f22IoZ3K0x4YHXy/kmErMhK/6Td5C9eLyma1xJoLQwCgy3SNtzA85nQck6GLtrkhvu/gbyjUlKrfR78Y/O0xkxAzWL+F+Fd08KMuPilAL30cYQIDAQAB:300

### this is just a checksum so Symbiosis knows whether the file was modified since Symbiosis last edited it.
# Checksum MD5 64a94c3fe158612cf213d8a5efe1ca38

Updated on April 15, 2020

Was this article helpful?

Yes No

Have you tried Kubernetes?

Kubernetes (K8s) is helping enterprises to ship faster & scale their business. Sounds good? Let us build a K8s solution for your needs.