Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc


Why run djbdns?

The Domain Name System or Domain Name Server (DNS) is a system that stores information associated with domain names in a Distributed Database on networks, such as the Internet. The domain name system (Domain Name Server) associates many types of information with domain names, but most importantly, it provides the IP address associated with the domain name. It also lists mail exchange servers accepting e-mail for each domain. In providing a worldwide keyword-based redirection service, DNS is an essential component of contemporary Internet use.DNS is useful for several reasons. Most well known, the DNS makes it possible to attach hard-to-remember IP addresses (such as to easy-to-remember domain names (such as "") Humans take advantage of this when they recite URLs and e-mail addresses. Less recognized, the domain name system makes it possible for people to assign authoritative names, without needing to communicate with a central registrar each time.


The alternative to djbdns is BIND. Numerous discussions and papers declare djbdns to be more secure and easier to configure than BIND, and more than sufficient for our purposes.

The Basics

Depending on your desired setup, there are two services that comprise djbdns. The Cache DNS Server (dnscache) or caching server, in a nutshell, simply caches dns lookups. Depending on the expire times listed in a DNS entry, the DNS caching server will either return the last known lookup it had, or go out and lookup a brand new entry.

For example: a user queries the dns cache server for The server does not know this address, so it goes out and queries and finds the correct IP (, returns it, and stores it (caches it) for future responses. A second user (or request) comes in, for The server has the last known IP (, and it is within the expire time, so it returns it.

The other service is the Authoritative DNS Server (tinydns), which maps entries from their canonical names to their IP addresses. This server can be run both "internally" and "externally" or public facing. Through the use of tinydns in conjunction with a dns caching server, you will have the potential for complete control over DNS services to a network.


One of the main complaints about djbdns is that, as it is usually not packaged in Linux distributions, it can be quite a pain to install. Luckily, with Gentoo, all you need is:

 # emerge djbdns

Daemontools will also be emerged as a dependency, and you will want to have it running, as it is the process that will start and monitor the various djbdns services:

 # /etc/init.d/svscan start
 # rc-update add svscan default

Note: depending on your setup you may need to do:

 # rc-update add svscan boot

instead. For example, when mounting network file systems at boot, the service will not be up in time.

Accounts named "tinydns," "dnscache," and "dnslog" should have been created. Check /etc/passwd to confirm:

 # grep dns /etc/passwd
 dnscache:x:101:200:added by portage for djbdns:/dev/null:/sbin/nologin
 dnslog:x:102:200:added by portage for djbdns:/dev/null:/sbin/nologin
 tinydns:x:103:200:added by portage for djbdns:/dev/null:/sbin/nologin

Important Note

Contrary to the monolithic BIND, djbdns has split the Cache DNS Server (dnscache) and Authoritative DNS Server (tinydns). Both will listen on port 53, which means that if you want to run both servers on the same box, you will have to bind them to different IP addresses. While this may sound like a limitation compared to BIND, this is actually a Very Good Thing™, as these two services should never run on the same IP anyway. For more information, you can check this explanation.

For a small network, one machine typically provides both name caching services via dnscachex for all machines on the network as well as publishing local domain name services via tinydns. IPs listed in /etc/resolv.conf of the other machines should point to a DNS cache and never to a name server [1]:

...the IP addresses listed in /etc/resolv.conf should never match any IP addresses listed in NS records.

For this reason, typical small networks should place dnscachex on a public address such as and this address should be entered into the /etc/resolv (or equivalent location for dns server information, e.g. On Windows: TCP/IP Properties -> DNS Servers) of all machines on the network. If you also want to publish the addresses of local domains then place tinydns on a private address such as and have dnscachex reference this name server by adding the proper file(s) in /var/dnscachex/root/servers/. See [2] for details.

For external Internet DNS service (e.g., usually two or more servers (most accredited domain registrars require two or more for reliability) all provide external domain name services via tinydns. They may also run dnscache locally to provide cached lookups to services running locally on the box, but for the main part all exist to respond to external queries.

Note: dnscachex is just a naming convention to identify a dnscache configured to serve more than just the local system. One could easily name the instance happy, sleepy, or dopey, as well. A local only cache would probably be bound to a loopback address therefore making it inaccessible to other systems; and the setup script will name it, by convention, dnscache instead of dnscachex.

DNSCache Server Setup

First we'll setup the DNS Caching Server. Depending on the nature of your setup, you might want to have your ISP's DNS server IP's handy to set up forwarding.

# dnscache-setup

Press enter twice, to begin the setup process, and to accept the default /var installation directory.

Currently running IP addresses:

IP to bind cache to []>

Here, type what IP address the DNSCache server will listen on. See the important note above. If you choose the localhost loopback IP, the installer will create the configuration directory /var/dnscache. If you choose the external IP, the directory will be /var/dnscachex.

 enter forward-to IP>

Here, you would typically input your ISP's DNS servers IP addresses. Press enter an extra time to stop adding them.

 Just hit Enter if you do not want to specify clients!

 Enter IP>

(Note: you will not see this step if you chose to bind DNSCache to This lets you specify which machines or subnets are allowed to connect to your DNSCache (by default, only localhost is allowed). Press enter an extra time to finish adding allowed clients. For example, to allow all hosts on 192.168.0.*, you would input: 192.168.0

The setup program will now backup your /etc/resolv.conf to /etc/resolv.conf.orig and set the nameserver in /etc/resolv.conf to the DNSCache IP address you provided in the first step. According to your setup, this may not be wanted, so be sure to fix your /etc/resolv.conf if necessary.

You will then see:

 dnscache is ready for startup.
 Do you want dnscache to be started and
 supervised by daemontools now?

 This requires svscan (daemontools) to be running currently and
 monitoring /service !!

 (press control-C to abort)

Almost there. Now press enter and a link to your configuration directory will be created for you in /service (effectively starting DNSCache if you have svscan running). You can also press control-C to just create the configuration directories without starting the server. To start the server later on, you will have to create the link manually:

 # ln -s /var/dnscache /service

THere is no need to do this with version : 1.05-r19

Note that according to your configuration, you may need to link /var/dnscachex instead.

TinyDNS Server Setup

Run the friendly TinyDNS setup utility as root.

 # tinydns-setup

Press enter twice, to begin the setup process, and to accept the default /var installation directory.

 IP to bind nameserver to>

Here, type what IP address the TinyDNS server will listen on. See the important note above. The installer will create the /var/tinydns and /var/axfrdns configuration directories.

 tinydns is ready for startup.
 Do you want dnscache to be started and
 supervised by daemontools now?

 This requires daemontools to supervise
 /service !!

 (press control-C to abort)

Almost there. Now press enter and links to your configuration directories will be created for you in /service (effectively starting TinyDNS if you have svscan running). You can also press control-C to just create the configuration directories without starting the server.

To start the server later on, you will have to create the links manually (There is no need to do this with version > 1.05-r19):

 # ln -s /var/tinydns /service
 # ln -s /var/axfrdns /service

Replicating DNS

The author of djbdns makes a commonsense point: "Your DNS servers don't have to be more highly replicated than your web servers, mail servers, etc." As such, there is little use in replicating your DNS Server for a one-box environment. See here for more details. If you need a third-party service for your secondary DNS server, consider

Because most modern registrars, however, require 2 or more DNS Servers for a DNS entry, often it becomes a necessary evil to replicate among two or more DNS servers a single entry. While it is true that in a one-box setup, if one server is unavailable, all services (including DNS, web, and mail) are unavailable, at least in a replicated environment, the other DNS servers can manually re-route the name lookups to a different box until the other server is back up....

For more on DNS replication see:

Accept the Delegation

 # cd /service/tinydns/root
 # ./add-ns
 # make

Replace with your domain name and with the IP address of the box you're making the DNS Server.

A Quick Breakdown

The above example (Accept the Delegation) is fine for a simple name server, but to really use tinydns, you'll want to add quite a bit more.

The /var/tinydns/root/data file is where all your DNS entries are stored. There are a number of scripts inside /var/tinydns/root that will help you add various lines to your data file. Whenever you edit the data file, be sure to run 'make' in the root dir to "compile" the data file into a tinydns readable file.

You can use the scripts to add nameservers, aliases, childns servers, mx servers, and regular hosts. After using the scripts, and seeing what they do, you might be comfortable enough to edit the data file directly. Here's an example data file:

  ## example tinydns data file
  ##  see for more info
  # SOA record for
  # Zfqdn      :mname        :rname             :ser       :ref  :ret :exp   :min :ttl  :timestamp :lo
  # sample name server 1
  # sample name server 2 (different server ideally in different location, but read the commonsense point above)
  # a full on record for the domain with the internet IP (
  # a mail (mx) record
  # an optional secondary mx (20) server (again, ideally in a different location)
  # definitions -- all the following are examples

Now you should have the base for hosting a domain. In your favorite registrar of domains, you can now register a name server or two ( with your IP) and then use that nameserver for hosting. You'll need at least two name servers to host a domain, but again read the common-sense point above. This example is of course, for hosting your own DNS, mail, and web (and anything server) on one server (with one optional backup).

If you'd like to host more domains on this one server -- say, for example, this host is a dedicated server sitting colocated somewhere with the IP, you can simply use the above as a template, and add more hosts. Your data file will just continue to grow. Ideally it would be great if you had two (or more) servers located in different locations physically, and you would use axfrdns to sync their tinydns data files.

Services Management

svc and svstat from Daemontools are used for djbdns services management. Unfortunately, these come with neither man pages nor usage string (unless you use the USE flag doc), so here is a quick primer:

 # svc -u /service/tinydns   # start (up) tinydns
 # svc -d /service/tinydns   # stop (down) tinydns
 # svc -t /service/tinydns   # reload tinydns
 # svstat /service/tinydns   # check that tinydns is running

Note that you can perform an action on all services at once. For example, to cause all services to reload:

 # svc -t /service/*

If things get really messed up, the supervise process may start spewing messages on your console. You will need to kill it and stop the service so you can fix the configuration. For that, do the following:

 # cd /service/tinydns
 # rm /service/tinydns    # To prevent the service from being restarted by svscan
 # svc -dx . log          # Stop the service and kill the supervise process

After your configuration is fixed, you will need to recreate the link in /service manually to restart the service.

For more information, check the Daemontools documentation.

Checking and Troubleshooting

Start by checking that the services are running, according to Daemontools:

 # svstat /service/*
 /service/axfrdns: up (pid 12626) 77422 seconds
 /service/dnscachex: up (pid 14304) 61700 seconds
 /service/tinydns: up (pid 12850) 75602 seconds

If you see that one of the services always has an uptime below 10 seconds, it means that it could not be started properly. Do you have another process already listening on port 53 of the IP that service is configured to run on? See the important note above. If you are sure that this is not the problem, check your configuration.

You can check that the servers are listening correctly using the netstat command. If you have, say, DNSCache running on and TinyDNS running on, the output should look like this:

 # netstat -a -n | grep ":53"
 tcp        0      0*               LISTEN
 tcp        0      0  *               LISTEN
 udp        0      0*
 udp        0      0  *

A very good tool for debugging DNS problems is the dig command, from the net-dns/bind-tools package. If you do not have it already:

 # emerge bind-tools

Now, to check the proper function of your DNSCache server and that forwarding is working, dig your DNSCache for the DNS information of some public host (replace by the IP of your DNSCache in the following):

 # dig @
 ; <<>> DiG 9.2.5 <<>> @
 ; (1 server found)
 ;; global options:  printcmd
 ;; Got answer:
 ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 971
 ;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0

 ;                        IN      A

 ;; ANSWER SECTION:         600     IN      A         600     IN      A         600     IN      A

 ;; Query time: 74 msec
 ;; WHEN: Fri Jun 10 15:48:03 2005
 ;; MSG SIZE  rcvd: 80

Note that as DNSCache does its caching job, subsequent calls should be answered significantly faster (check the "Query time").

To check that your TinyDNS is correctly serving your domain with authority (replace 204.69.324.1 by the IP of your TinyDNS, and by a name that should be served by it):

 dig @

 ; <<>> DiG 9.2.5 <<>> @
 ; (1 server found)
 ;; global options:  printcmd
 ;; Got answer:
 ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 32434
 ;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 2, ADDITIONAL: 2

 ;                    IN      A

 ;; ANSWER SECTION:             300     IN      A

 ;; AUTHORITY SECTION:             86400   IN      NS             86400   IN      NS

 ;; ADDITIONAL SECTION:         86400   IN      A         86400   IN      A

 ;; Query time: 130 msec
 ;; WHEN: Fri Jun 10 16:20:44 2005
 ;; MSG SIZE  rcvd: 128

Check for the "AUTHORITY" section.

If this applies to your setup, you can also check that DNSCache and TinyDNS are correctly talking to each other, by asking DNSCache for a name served by TinyDNS (replace by the IP of your DNSCache, and by a name that should be served by TinyDNS):

 # dig @

 ; <<>> DiG 9.2.5 <<>> @
 ; (1 server found)
 ;; global options:  printcmd
 ;; Got answer:
 ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 11158
 ;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

 ;                   IN      A

 ;; ANSWER SECTION:            84259   IN      A

 ;; Query time: 2 msec
 ;; WHEN: Fri Jun 10 16:41:01 2005
 ;; MSG SIZE  rcvd: 45

Now, if you are installing an Authoritative DNS Server, you want to make really sure it's working not just for you but also for the rest of the Internet. In particular, if you are on a NATed LAN, you want to make sure things are working from the outside. If you do not have easy access to another Internet connection, you can use an online dig service. If all is well, you can now tell your registrar about your new name server, and enjoy.

Giving Back

The author of djbdns asks a few small favors, which you should consider:

Set up a public web page saying that your DNS server is powered by djbdns, so that a Google search for powered djbdns will find your page in a few months. These public statements will encourage other people to deploy djbdns, provide djbdns support services, and develop djbdns-related tools. Please also consider making a donation to the Bernstein Writing Fund.

Additional Links

Retrieved from ""

Last modified: Mon, 23 Jun 2008 21:23:00 +0000 Hits: 53,749