We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How To Set Up the Unbound Caching DNS Resolver on FreeBSD 10.1

Posted Aug 12, 2015 13.9k views DNS FreeBSD

How To Set Up the Unbound Caching DNS Resolver on FreeBSD 10.1 or 10.2


The system of domain name servers (DNS) is a global hierarchy of databases dedicated to the simple but essential task of looking up host names like www.digitalocean.com and turning them into one or more IP addresses. Whenever an email is sent or a connection to a host is initiated by its name, the DNS system is used. There is a good introduction to the DNS system available from the DigitalOcean community.

Such an essential and fundamental component of Internet infrastructure gets a lot of use. It is not uncommon for a busy system to make hundreds of name lookups per second or more. If services running on your server perform much work at all behind the scenes then it is likely that security and performance will benefit from verifying and caching within your own systems the name lookups that your service performs to conduct its operations.

In this tutorial, you will learn how to set up a FreeBSD server to remember all DNS lookups in a system-wide cache. Information will automatically expire from this cache, honoring each looked-up domain's individual policy for rechecking.


In order to follow this tutorial, you will need:

  • One FreeBSD 10.1 Droplet

Step 1 — Enabling Unbound

FreeBSD 10.1 includes the verifying caching resolver Unbound (version 1.4.22) as part of the base system; FreeBSD 10.2 includes version 1.5.3. Both are considered secure and ready to be put into production use.

Once you are logged into your server via SSH, enabling FreeBSD's included resolver is as simple as issuing the following command:

  • sudo sysrc local_unbound_enable=YES

Your Droplet is now configured to start Unbound at the next system reboot.

Step 2 — Starting Unbound

You can fire up the resolver immediately without performing a full system restart.

To start the resolver:

  • sudo service local_unbound start

If Unbound starts successfully you should see output similar to the following:

Performing initial setup.
Extracting forwarders from /etc/resolv.conf.
/var/unbound/forward.conf created
/var/unbound/lan-zones.conf created
/var/unbound/unbound.conf created
/etc/resolvconf.conf created
original /etc/resolv.conf saved as /etc/resolv.conf.20150812.184225
Starting local_unbound.

You are now running the Unbound verifying caching name resolver but not all of your currently running software is guaranteed to notice and pick up the modification.

Step 3 — Preserving This Setup Through Droplet Restoration

Actions like restoring a backup image or using a snapshot image as the basis for a new Droplet would normally clobber the configuration we've done so far. This is due to a minor bug in the OpenStack driver for FreeBSD. Luckily this bug has been fixed in the upcoming release. We will individually apply this particular patch to the current release now in order to ensure Unbound's proper operation with DigitalOcean's backup and snapshotting facilities.

Download the patch from the official repository for BSD-CloudInit, (the FreeBSD OpenStack driver):

  • fetch https://github.com/pellaeon/bsd-cloudinit/commit/a7ee246c23.diff

Apply the patch to the proper file:

  • sudo patch -N -F3 /usr/local/bsd-cloudinit/cloudbaseinit/osutils/freebsd.py < a7ee246c23.diff

You should see output that ends with the following, indicating the patch applied successfully:

. . .
Patching file /usr/local/bsd-cloudinit/cloudbaseinit/osutils/freebsd.py using Plan A...
Hunk #1 succeeded at 4 with fuzz 2 (offset 1 line).
Hunk #2 succeeded at 83 with fuzz 3 (offset 4 lines).

You no longer need the patch file and may remove it:

  • rm a7ee246c23.diff

Your system is now configured to use Unbound through system backups and restorations, or after being cloned to an entirely new server.

Step 4 — Restarting Affected Services

The simplest way to ensure all of your software is using the new resolver is to restart the Droplet entirely.

You can delay doing this until it least impacts the service your Droplet provides. The running software will use either the old resolver or the new one, rather than malfunction; any software that is able to pick up the transition in the meantime will do so gracefully. and there should be no ill effects from both being potentially in use side by side temporarily.

When you are ready, restart your Droplet:

  • sudo shutdown -r now

That's all there is to it!


In this tutorial you learned how to cache host name and domain name lookups on your system and why you might want to do so. You can learn more about FreeBSD's caching resolver at the homepage for the Unbound project.


Creative Commons License