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

Published on August 12, 2015
How To Set Up the Unbound Caching DNS Resolver on FreeBSD 10.1


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.

Note: As of July 1, 2022, DigitalOcean no longer supports the creation of new FreeBSD Droplets through the Control Panel or API. However, you can still spin up FreeBSD Droplets using a custom image. Learn how to import a custom image to DigitalOcean by following our product documentation.


In order to follow this tutorial, you will need:

  • One FreeBSD 10.1 server

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:

  1. sudo sysrc local_unbound_enable=YES

Your server 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:

  1. 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 Server Restoration

Actions like restoring a backup image or using a snapshot image as the basis for a new server 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 your cloud provider’s backup and snapshotting facilities.

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

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

Apply the patch to the proper file:

  1. 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:

  1. 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 server entirely.

You can delay doing this until it least impacts the service your server 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 server:

  1. 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.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us

About the authors

Default avatar

staff technical writer

hi! i write do.co/docs now, but i used to be the senior tech editor publishing tutorials here in the community.

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel