tinydns — a general-purpose content DNS server using the UDP protocol




tinydns is a content DNS server that speaks the DNS/UDP protocol. It accepts DNS queries from hosts around the Internet, and responds with locally configured information.

When it starts tinydns changes its root to the directory specified by the ROOT environment variable, and drops privileges to run as the user ID and group ID specified by the UID and GID environment variables. The latter can be set up with envuidgid(1).

Normally tinydns is run via a server program such as udp-socket-listen to listen for DNS/UDP queries from hosts around the Internet. It understands the LISTEN_PID and LISTEN_FDS environment variable convention for having an already-listening socket passed to it by such a program, and uses the last open file descriptor in the list that refers to a UDP/IPv4 socket. If no such open file descriptor is provided it falls back to opening its own UDP/IPv4 socket, bound to port 53 of the IP address given by the value of the IP environment variable. It does not handle DNS/TCP.

tinydns rejects zone-transfer requests, inverse queries, non-Internet-class queries, truncated packets, and packets that contain anything other than a single query.


tinydns answers queries as specified by data.cdb, a binary file in its root directory created by tinydns-data(1).

tinydns includes NS records with answers to most queries. This increases DNS packet sizes, but it draws queries away from parent servers, and reduces the frequency of long DNS delays. With the default cache times, a client that uses a normal record at least once every day will always have the corresponding NS records cached and will never have to talk to parent servers.

If a record set has ending time ("time to die") for the information; tinydns dynamically adjusts the TTLs that it publishes so that the records are not cached for more than a few seconds past the ending time.

SOA resource records inform tinydns what requests to answer. It will only answer at all for domain names where there is a SOA resource record at or above that domain name in the namespace.

There can be many SOA resource records for a domain, as the result of many . lines in the source data file. tinydns will return only one SOA record per domain when the request is actually for a domain's SOA resource record set.

NS resource records inform tinydns about delegation points (when they are not accompanied by SOA resource records). It will always answer with a delegation response for domain names at or below a delegation point in the namespace.

tinydns returns IP addresses (i.e. A or AAAA records generated from + or = or @ or . or & lines in the source data file) in a random order in the answer section. If there are more than 8 records, it returns a random set of 8.


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

For example, the lines (as written in the original database source file)

have the same effect as

and so on.

As another example, the lines

have the same effect as

and so on.

Notice that the wildcard does not apply to, because that name has its own records.


tinydns was originally part of Daniel J. Bernstein's djbdns toolset in 1999.


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