This document lives at

This document applies to dnscache-1.00, djbdns-1.01 through -1.05.

Setting up djbdns for use on dial-up connections

djbdns is a collection of DNS client, server (including cache) tools which are secure, fast, have a small memory foot print and are easy to set up. And they haven't caused CERT advisories so far, much unlike BIND.

Legal mumbo-jumbo

This document is copyrighted work. It is © copyright 2000/2001 by Matthias Andree.

You may freely copy it as long as you do not modify anything. Daniel J. Bernstein, author of djbdns, is hereby explicitly permitted to include this information into the FAQ accompanying djbdns as long as that software is freely available for all kind of use.

This document shows a procedure meant to simplify the use of dnscache on dial-up connections.

It will alter djbdns' behaviour. Do not contact Daniel J. Bernstein or his mailing list after you have altered your system as shown below. Contact the author of this document instead, find his address at the bottom.

Goal (the problem you may have)

If you are using djbdns (formerly known as dnscache) on a dial-up machine, you may have noticed that Netscape will hang if you're offline and resolving domains takes a lot of time until you finally get the error message. This document outlines how to alleviate this.

Solution (how to get immediate error responses from djbdns)

There is a way to prevent the timeouts by hiding the root servers' IPs from dnscache and restarting it. After you followed the procedure shown below, djbdns will immediately return "host not found, try again" condition if you try to resolve an external domain while you are off-line. Note that "delegations" for local domains are unaffected, i. e. if you pointed your dnscache to a tinydns at to resolve corp.local domains, dnscache would still resolve these.

This document assumes you have installed a local or external (or both) dns cache as outlined in djbdns' setup instructions. I'm showing this setup for an external cache, but it works for a local cache the same way.

Note the actual difference between internal and external dnscaches consists of the files in root/ip/ in external caches while a local cache only has the root/ip/ file.

Note that this prodecure will erase djbdns' cache each time you go online or offline.

  1. cd to your dnscache service directory, usually /service/dnscachex or /service/dnscache for a local cache.
  2. cd root/servers
  3. cp @ ../root
  4. >../empty
    NOTE: For djbdns 1.03 and newer, if you are using FORWARDONLY, and you have servers you still want to forward to when off-line, write these into empty.
  5. edit your ip-up script (example: /etc/ppp/ip-up) so that upon going on-line, your script links root to @ and restarts dnscache, try these lines:
    ln -sf ../root /service/dnscachex/root/servers/@
    svc -h /service/dnscachex
    (remember to adjust your service path accordingly)
  6. edit your ip-down script (or the ip-down section in your ip-up script, should the former be a symlink to the latter) so that upon going off-line, your script links empty to @ and restarts dnscache, try these lines:
    ln -sf ../empty /service/dnscachex/root/servers/@
    svc -h /service/dnscachex
    (again, remember to adjust your service path accordingly)

That should be it. The next time you go online or offline, dnscache will be restarted with the appropriate root servers file @.

Reverting these changes

Should you for whatever reason want to restore the original behaviour, follow these steps:

  1. cd to your dnscache service's root/servers directory, usually /service/dnscachex/root/servers, see above under 1. and 2. for details.
  2. rm @ (this gets rid of the symlink)
  3. mv ../root @
  4. rm ../empty
  5. svc -h /service/dnscachex

Done. DNSCache should behave as before.


If you happen to have erased your original @ file:

dnscache 1.00 and djbdns 1.01

Just unpack the original dnscache or djbdns archive and move the @ file into place.

djbdns 1.02 to 1.05

copy /etc/ into place. (Use dnsroots.local instead if you have that.)

Additional software

I have a patch against djbdns 1.00 here which allows for sending dnscache a SIGHUP to have it re-read its configuration file. It will not lose its cache, if you use svc -h instead of svc -t. Note that on an unpatched dnscache, svc -h will have the same effect as svc -t, namely killing dnscache, which will be re-started by supervise then.

External Links

djbdns related

not djbdns related

History of this document

(This will not mention changes to the spelling or layout unless in example code.)

Add Links section, fix JavaScript bugs for Opera.
Fix remaining issues to satisfy W3C HTML Validator
Add note about FORWARDONLY. Review for 1.05. Add frame smasher. Run through nsgmls to validate.
add note of what djbdns is
add /etc/dnsroots.{global,local} information
review information contained for djbdns-1.03 and 1.04
review information contained for djbdns-1.02
add link to djbdns SIGHUP patch, switched to svc -h, added explanation
moved the root and empty files up one level, added troubleshooting and history sections and information on the difference between local and external cache.
Initial draft and announcement on

Author of this document

Matthias Andree <>

Valid HTML 4.01!