Table of Contents
recursive toc v1.4

tinydns data file: quick configuration guide

tinydns data file: quick configuration guide

Pedro Venda

Lisbon, 22 January, 2006

This document is a very brief hands-on description of the tinydns data file syntax. It features a table with all (or nearly all) kinds of configuration lines and an example domain written in 3 equivalent but different ways.

Index

1. Copyright, acknowledgements, updates and feedback

2. What, Why and to Whom?

3. General configuration notes

This is NOT the main part of the document, but if you don't know tinydns well, it is important to read these notes at least once before diving into the configuration lines. Near the configuration syntax descriptions are links for these notes where needed. data.cdb is the data file tinydns uses internally in runtime. This file however is converted explicitly from a text file called data.

In this text file, each line starts with a special "code" character that defines the purpose and syntax of the rest of the line, generally representing a dns record. Each record is made up of one or several fields delimited by commas. Some fields are optional and may be left blank. Commas delimiting empty fields or spaces and tabs at the end of the lines can be ommited.

Common fields in several types of records are defined next:

fqdn
Fully qualified domain name. Something like example.net or host.example.net.
x
Host name. If x has a dot in it, it'll be treated literally, as hostname x - for example x could be mail.example.net.
Otherwise, it will be treated as x.RR.fqdn where RR could be ns, mx, etc. depending on the record type - for example if x is just mail in an MX record, tinydns interprets it as mail.mx.example.net.
ip
Valid ip address written as a.b.c.d. For example 192.168.45.5 is a valid ip address.
ttl
Time To Live. Number of seconds the line's dns record may be cached; this field may be left blank: tinydns figures out sensible values for ttl.
timestamp
External TAI64 timestamp printed as 16 lowercase hex characters. Depending on the value of ttl, this timestamp has one of two possible meanings:
  • ttl is ommited or non-zero: timestamp is starting time for the line's information
  • ttl is 0: timestamp is the ending time for the line's information
lo
Client location. This is the location identifier for clients. It must be a sequence of one or two lettres. Clients are only in one location.
ipprefix
Ip prefix for client locations. A client with ip 192.168.45.12 and another with 192.168.45.36 would match an ip prefix of 192.168.45. Longer prefixes override shorter ones; 192.168 overrides 192.

4. Data file syntax table

This section is the juice of the whole article. It resumes most types (if not all) of DNS records and other configuration lines

Code Syntax Function(s)
# #comment Comment line
  • Makes data file easier to read.
  • Comment lines are obviously ignored by tinydns
% %lo:ipprefix Client location range
  • Specifies location sets for clients based on ip ranges. Clients with ip addresses starting with ipprefix are in location lo.
. .fqdn:ip:x:ttl:timestamp:lo SOA, NS and A records
  • Creates an NS record showing x.ns.fqdn
  • Creates an A record for x.ns.fqdn - ip
  • Creates an SOA record for fqdn listing x.ns.fqdn as the primary NS and hostmaster@fqdn as contact address.
& &fqdn:ip:x:ttl:timestamp:lo NS and A records
  • Creates an NS record showing x.ns.fqdn
  • Creates an A record for x.ns.fqdn - ip
= =fqdn:ip:ttl:timestamp:lo A and PTR records
  • Creates an A record for fqdn - ip
  • A PTR record showing hostname fqdn as the name of d.c.b.a.in-addr.arpa, assuming ip is a.b.c.d
An NS record should exist somewhere for some prefix of fqdn and another (or the same) for d.c.b.a.in-addr.arpa.
+ +fqdn:ip:ttl:timestamp:lo A record
  • Creates an A record for fqdn - ip
An NS record should exist somewhere for some prefix of fqdn and another (or the same) for d.c.b.a.in-addr.arpa.
@ @fqdn:ip:x:dist:ttl:timestamp:lo MX record
  • Creates an MX record showing x for domain fqdn at distance dist.
- -fqdn:ip:ttl:timestamp:lo Temporarily disabled record
  • This record is ignored by tinydns
' 'fqdn:s:ttl:timestamp:lo TXT record
  • Creates a TXT record for fqdn containing the string s
  • Octal codes (\nnn) can be used to introduce arbitrary data
^ ^fqdn:p:ttl:timestamp:lo PTR record
  • Creates a PTR record for fqdn pointing to the host name p
C Cfqdn:p:ttl:timestamp:lo CNAME record
  • Creates a CNAME record for fqdn pointing to the host name p
Z Zfqdn:mname:rname:ser:ref:ret:exp:min:ttl:timestamp:lo SOA record
  • Creates a Start of Authority record for fqdn with the following settings:
    • Primary name server: mname
    • Contact address: rname (first . changed to @)
    • Serial number: ser
    • Refresh time: ref (defaults to 16384s if omitted)
    • Retry time: ret (defaults to 2048s if omitted)
    • Expire time: exp (defaults to 1048576s if omitted)
    • Minimum time: min (defaults to 2560s if omitted)
: :fqdn:n:rdata:ttl:timestamp:lo Generic record
  • Creates a record of type n for fqdn showing rdata
  • n must be an integer between 1 and 65535 but not 2 (NS), 6 (CNAME), 12 (SOA), 15 (MX) or 252 (AXFR). These record types are setup through the above configurations
  • The format of rdata depends on the record type (n)
  • Record types can be found here http://www.iana.org/assignments/dns-parameters

5. Example data files for one domain configuration

Let's assume the following settings and hosts for the example domain:

Name example.net
IP Network 192.168.45.0/255.255.255.0
Primary nameserver ns.example.net
Secondary nameserver ns2.example.net
Primary mail exchanger relay.example.net
Secondary mail exchanger relay2.example.net
Hostmaster email hostmaster@example.net
Delegation of domain dmz.example.net to ns.dmz.example.net with IP Network of 192.168.90.0/255.255.255.0
Host list
ns.example.net 192.168.45.1
ns2.example.net 192.168.45.2
relay.example.net points to 192.168.45.1
relay2.example.net points to 192.168.45.2
gateway.example.net 192.168.45.254
nscache.example.net alias to gateway.example.net
ns.dmz.example.net 192.168.90.1

The above information defines a simple domain with respective nameservers and mail exchangers. The following configuration files are two examples of tinydns configuration files implementing the domain above.

Both configuration files generate equivalent tinydns settings (apart from one small detail: the hostmaster email address) differing only on the text representation of those settings: one being denser than the other.

Compact; small and tidy

example-compact.txt 
# compact tinydns data file

.45.168.192.in-addr.arpa:192.168.45.1:ns.example.net:::
&45.168.192.in-addr.arpa:192.168.45.2:ns2.example.net:::
@45.168.192.in-addr.arpa:192.168.45.1:relay.example.net:10
@45.168.192.in-addr.arpa:192.168.45.2:relay2.example.net:20
# A, NS and SOA records for example.net; hostmaster mail address 
#                 is the implicit default hostmaster@example.net
.example.net:192.168.45.1:ns.example.net::
&example.net:192.168.45.2:ns2.example.net:::
@example.net:192.168.45.1:relay.example.net:10
@example.net:192.168.45.2:relay2.example.net:20

^1.45.168.192.in-addr.arpa:ns.example.net:::
^2.45.168.192.in-addr.arpa:ns2.example.net:::

=gateway.example.net:192.168.45.254:::
Cnscache.example.net:gateway.example.net:::

# SUB DOMAIN DELEGATION
&dmz.example.net:192.168.90.1:ns.dmz.example.net:::

Verbose; easy to read and interpret

example-verbose.txt 
# verbose tinydns data file

#
# REVERSE ZONE
#
# (reverse) dns servers: primary and secondary
Z45.168.192.in-addr.arpa:ns.example.net:hostmaster.example.net::::::::

# NS records
&45.168.192.in-addr.arpa::ns.example.net:::
&45.168.192.in-addr.arpa::ns2.example.net:::

# MX handlers
@45.168.192.in-addr.arpa::relay.example.net:10
@45.168.192.in-addr.arpa::relay2.example.net:20

#
# FORWARD ZONE:
#
# SOA record: primary nameserver is ns.example.net and hostmaster
#             mail address is hostmaster@example.net
#             (the 'Z' configuration line is the only one that
#             allows specifying the hostmaster mail address)
Zexample.net:ns.example.net:hostmaster.example.net::::::::

# NS records: primary and secondary nameservers
&example.net::ns.example.net:::
&example.net::ns2.example.net:::

# MX records: relay.example.net, distance = 10
#             relay2.example.net, distance = 20
@example.net::relay.example.net:10
@example.net::relay2.example.net:20

# A records: ns.example.net, ns2.example.net
=ns.example.net:192.168.45.1:::
=ns2.example.net:192.168.45.2:::

# PTR records: relays are in the same hosts as dns servers
+relay.example.net:192.168.45.1:::
+relay2.example.net:192.168.45.2:::

# more A records: gateway.example.net
=gateway.example.net:192.168.45.254:::

# CNAME record: nscache.example.net is alias to gateway.example.net
Cnscache.example.net:gateway.example.net:::

#
# SUB DOMAIN DELEGATION
#

# NS record
&dmz.example.net::ns.dmz.example.net:::

# A/PTR record for nameserver
=ns.dmz.example.net:192.168.90.1:::

6. References

  1. Official tinydns-data documentation
  2. Domain name system parameters
  3. DNS Resource Records
  4. How to run a DNS server

Creative Commons License
This work is licensed under a Creative Commons Attribution 2.5 License.