D. J. Bernstein
Internet publication
djbdns

How to run an external forwarding cache

Here is how to set up your computer so that it uses another computer to find addresses of Internet hosts, and remembers the addresses for future use. The other computer is set up by your Internet service provider to run an external DNS cache. These instructions are more complicated than the non-forwarding external cache instructions, but they provide better performance if your computer has a slow Internet connection.

With these instructions, your computer will run an external cache that other computers can use. This means that there will be two external caches: your new external cache, and your ISP's external cache. In contrast, with the internal forwarding cache instructions, your computer's cache will be used only by your computer.

If your computer is running a DHCP client to obtain a dynamically assigned IP address from your ISP, and if your DHCP client cannot be configured to make external DNS cache information available to dnscache, you will have to use the non-forwarding external cache instructions instead of these instructions.

These instructions assume that you have already installed daemontools and djbdns (version 1.03 or above), and that svscan is already running.

1. As root, create UNIX accounts named Gdnscache and Gdnslog.

2. Figure out the IP address that you want to use for your new external cache. This address must be configured on your computer and accessible to the other computers on your network. The following instructions assume that your network uses private 10.* addresses and that your new external cache will use the address 10.53.0.1.

3. As root, create an /etc/dnscache service directory, with your IP address on the end of the line:

     dnscache-conf Gdnscache Gdnslog /etc/dnscache 10.53.0.1
This directory contains logs and a few configuration files that you can change later.

4. If your computer is running a DHCP client to obtain a dynamically assigned IP address from your ISP, configure the DHCP client to make external DNS cache information available to dnscache, and skip to step 8.

5. Find out the IP address of the ISP's external cache. Many ISPs call this the ``DNS server address.''

6. Check that your computer can talk to the ISP's external cache. For example, if the IP address of the ISP's cache is 1.2.3.4:

     env DNSCACHEIP=1.2.3.4 dnsqr a www.aol.com
Normally dnsqr will instantly print various lines such as ``answer: www.aol.com 3600 CNAME www.gwww.aol.com.'' If dnsqr instead pauses for a minute and prints ``timed out,'' your computer is not properly attached to your ISP's network (or the ISP's cache is down). You may have a firewall interfering with your computer's Internet access; if so, tell your firewall to allow UDP and TCP from this computer's ports 1024 through 65535 to the ISP's cache's port 53.

7. As root, put the IP address of the ISP's external cache into /etc/dnscache/root/servers/@, replacing the previous contents of that file. For example, if the IP address of the ISP's external cache is 1.2.3.4:

     echo 1.2.3.4 > /etc/dnscache/root/servers/@

8. As root, create /etc/dnscache/env/FORWARDONLY:

     echo 1 > /etc/dnscache/env/FORWARDONLY

9. As root, tell svscan about the new service, and use svstat to check that the service is up:

     ln -s /etc/dnscache /service/dnscache
     sleep 5
     svstat /service/dnscache

10. As root, create entries in /etc/dnscache/root/ip showing which client IP addresses are authorized to use your new cache. For example,

     touch /etc/dnscache/root/ip/10
authorizes all clients with IP address 10.* to use this cache. You can add or remove addresses later.

11. Whenever you add a client computer, set it up to use this cache: as root, on the client computer, put

     nameserver 10.53.0.1
into /etc/resolv.conf, replacing any previous nameserver lines.

12. Check whether you can look up addresses of some Internet hosts:

     dnsip www.cnn.com
     dnsip www.fsf.org
Then try surfing the web. If you want to see what dnscache is doing behind the scenes, read /service/dnscache/log/main/current.

13. Set up a public web page saying that your DNS cache 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.