DNS Stack

This page has the purpose to document the Koozali SME Server DNS Stack. It is based on djbdns software, from which we use two programs: dnscache and tinydns.

Globally the stack has a DNS cache answering the client from his cache, and getting missing bits depending on its configuration : local things will go to tinydns, remote things will ask to remote ROOT DNS server using dnscache.forwarder.

There is no ip v6 implementation, except by patching http://www.fefe.de/dns/

TinyDNS

This is the software holding the DNS entry for all the local hosts and local domains. It resides in /var/service/tinydns. It is supervised by runit. So you can find a "run" script there where all the recipe to launch the service is. As per SME 10, the instance is called by a systemd service unit, but still under runit supervision.

By default tinydns listen on 127.0.0.1:53 UDP.

In the root subfolder lives the list of known zones. the file /var/service/tinydns/root/data is templated. It is populated using flat db files hosts and domains.

Prefixes:

• C creates a CNAME record
• = creates A and PTR records
• +creates a A record without PTR record
• @ creates a MX and a A records
• . for a NS record
• & creates a NS and a A records
• ^ creates a PTR record
• ' creates a TXT type record
• Z creates a SOA record
• : creates a generic record ... :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). The proper format of rdata depends on n. You may use octal \nnn codes to include arbitrary bytes inside rdata.
• # comment

NS

a NS entry for every entries of domain type pointing to the SME Server itself as authority

a NS entry for the local reverse zone

# NS Records
.sme-server::sme10.test10.domain.com

MX

a MX entry for every entries of domain type pointing to the SME Server

# MX Records
@sme-server::sme10.test10.domain.com

A

a A entry for every domains of domain type in domains db

a A entry for every hosts defined of every domains of domain type in domains db

# A Records for domains
+sme-server:192.168.1.1

a generic A entry for every pc on the LAN

# Generic A Records for test10.domain.com
+pc-00001.test10.domain.com:192.168.1.1
=pc-00001.test10.domain.com:192.168.1.2

DNScache

Dnscache is the service listening to dns query from LAN and localhost. It listens on localIP:53 TCP and UDP. Youcan alter that using the ListenIP property, it also listen to all IP, but this can be altered using SendIP property. It resides in /var/service/dnscache. It is supervised by runit. So you can find a "run" script there where all the recipe to launch the service is. As per SME 10, the instance is called by a systemd service unit, but still under runit supervision. in root/ip subdirectory are ip authorized to query to the cache. In root/servers/ are a list of domains the cache knows where to query. If a file exist for the needed domain, then dnscache query to one of the DNS server in the file. If a domain is not stated there, then dnscache looks to the file @. As a default it redirects to dnscache.forwarder 127.0.0.2:53 . All SME locally handled domains have a file there and the server inside the file is the tinidns service address: 127.0.0.1

DNScache.forwarder

Dnscache.forwarder is the service listening to dns query from LAN and localhost. It listens on 127.0.0.2:53 UDP. It resides in /var/service/dnscache.forwarder. It is supervised by runit. So you can find a "run" script there where all the recipe to launch the service is. As per SME 10, the instance is called by a systemd service unit, but still under runit supervision. in root/ip subdirectory are ip authorized to query to the cache (only 127.*). In root/servers/ are a list of domains the cache knows where to query. First you see the generik @. As a default it redirects to a list of ROOT DNS seeds. If dnscache properties Forwarder and Forwarder2 exists then the list is replaced by those values. And the second file is "127.in-addr.arpa" that redirects to tinydns.

Use cases

I want to define a remote DNS server for a domain

db domains set myremotedomaine.cc domain-remote Nameservers=IP1,IP2
db domains set myremotedomaine.com domain-remote Nameservers=IP3
signal-event domain-modify

I want to add a pihole

If you wan to add a pihole to remove some ads. The easy solution is to put it as dnscache Forwarder property, but the result is you might get generic results for your server.

config setprop dnscache Forwarder mypiholeip

Another option could be to play at the dhcpd level and do not mess with the server but, this will prevent the lan pc to get local domains from the SME, unless you then specify to the pihole to ask to your sme for known local domains. See Pihole

I want to insert X dns service in the stack

You could set dnscache to listen on 127.0.0.3:53 (ListenIP). Then set your new service to listen on localIP. If you need your server to also listen on 127.0.0.1:53, then you need to do the same for tinydns with ListenIP to 127.0.0.4:53. Only issue there the file /var/service/dnscache.forwarder/127.in-addr.arpa (containing 127.0.0.1) is owned by e-smith-dnscache and not templated, so it will point to your new service and not to tinydns.

You could then configure your new service to call dnscache or tinydns for local domain, or could simply replace them totaly by rewriting all existing code, and support all contribs depending on them.

Sources

• http://cr.yp.to/djbdns/tinydns-data.html