Configuring Unbound to use OpenNIC

In addition to the basic unbound configuration, you may want to specify servers to use for forwarding.

In this article, we provide a step-by-step guide for adding DNS servers from OpenNIC to use as forwarding servers for unbound(8).

Obtaining Nameserver IP addresses

Before you begin, you will need a list of IP addresses for DNS servers to use. We will use OpenNIC's servers. Because OpenNIC's list of servers change regularly, you should also regularly update the IP addresses you use in unbound.conf(5).

WARNING: If the forwarding addresses used in unbound.conf(5) become out-of-date, name lookup may fail, causing many networking issues for your system.

There are two quick methods for quickly obtaining the IP addresses from OpenNIC:

Shell script

First, you can download this shell script and execute it.

Note: You will need to first install curl in order to use the shell script:

# pkg_add curl

Browser Javascript

Alternatively, open up your web browser's javascript console window and run this command:

document.clear();data=document.querySelectorAll("html body div#frame div#view div#srvlist div p");document.body.innerText="forward-addr: 134.195.4.2";data.forEach(line=>{
if (line.childNodes[0].childNodes[1].title == "No logs kept"){
document.body.innerHTML+=`<br>forward-addr: ${line.childNodes[2].childNodes[0].data}`;
}
});

Adding the forwarding zone

Once you obtain the list of forwarding servers, append them to the bottom of unbound.conf(5) as follows:

forward-zone:
        name: "."                               # use for ALL queries
forward-addr: 192.0.2.1
forward-addr: 198.51.100.2
forward-addr: 203.0.113.3

The forward-addr lines indicate which nameserver unbound will query.

WARNING: The above IP addresses are not real. Do not use them. Instead, use the IP addresses from OpenNIC's list of servers.

Disable DNSSEC

OpenNIC servers do not appear to support DNSSEC. For this reason, you may need to disable DNSSEC in order for the forwarding servers to work properly. Comment out three lines related to DNSSEC as shown below:

#       auto-trust-anchor-file: "/var/unbound/db/root.key"
#       val-log-level: 2

#       aggressive-nsec: yes

WARNING: If DNSSEC is enabled, and the forwarding nameserver does not support DNSSEC, lookup using unbound(8) will fail.

Troubleshooting

Forwarding Servers

Invalid Nameservers

After setting the forwarding servers, you may find unbound is unable to query any domain. For example, if you attempt to use host, you might receive a connection timed out error or a SERVFAIL error:

$ host example.com
;; connection timed out; no servers could be reached

$ host example.com
Host example.com not found: 2(SERVFAIL)

This may be that your forwarding servers are not setup correctly, or the list of IP addresses you used are no longer valid. Remember, the list of OpenNIC servers changes frequently and must often be updated!

First, check if forwarding servers have been configured, and which ones are being used:

# unbound-control forward
134.195.4.2
...

Try disabling the forwarding servers and using root nameservers instead, then query again:

# unbound-control forward off
ok
# host example.com
example.com has address 93.184.215.14
example.com has IPv6 address 2606:2800:21f:cb07:6820:80da:af6b:8b2c
example.com mail is handled by 0 .

Disabling forwarding servers often works if invalid nameservers are specified as forwarding servers in unbound.conf(5). This can happen if you forgot to update the list of OpenNIC nameservers and have an obsolete list of nameservers.

DNSSEC Not Supported

If you are certain the nameservers are valid, but they do not work unless forwarding is disabled with unbound-control(8), then the nameservers may be buggy or non-DNSSEC supporting.

Unbound's system logs (default /var/log/daemon) may indicate the cause of failure. In this sample log, validation is failing because the nameserver does not support DNSSEC:

Dec 15 16:17:19 hostname unbound: [18434:0] info: failed to prime trust anchor -- DNSKEY rrset is not secure . DNSKEY IN

In this case, you can either disable DNSSEC (as indicated earlier) or use a nameserver that does support DNSSEC.

Update forwarding servers

Remember, disabling forwarding servers is only a temporary fix. If you want to use forwarding servers, the permanent fix is to edit your unbound.conf(5) to use valid forwarding servers.