Troubleshooting¶

Fixes for the problems you are most likely to hit with Unbound DNS Resolver. Each entry gives the symptom, the usual cause, and what to do.

Queries from another host are refused or time out¶

Cause: by design, the resolver listens on 127.0.0.1 and answers only 127.0.0.1.

Fix: add an interface and an access-control allow rule for your clients, restart Unbound, and open port 53 in the security group, as described in Answer queries from your VPC. A dig from the instance with -b 127.0.0.2 is refused on purpose.

A private zone does not resolve, or returns SERVFAIL¶

Cause: Unbound does not know where the zone lives, or the zone is not DNSSEC-signed and fails validation.

Fix: add a forward zone with domain-insecure, as described in Forward a private zone.

An internal name resolves, but the answer has no address¶

Cause: answers that point into private or link-local address ranges are stripped for names that are not marked as private.

Fix: add private-domain: "<zone>." for that zone.

`app.broken.test` returns SERVFAIL¶

This is expected. broken.test is the negative DNSSEC check: its trust anchor matches no key, so validation fails.

`app.secure.test` starts returning SERVFAIL after a year¶

Cause: the test zone's signatures last 365 days from first boot.

Fix: sign the zone again. Stop both services, remove the keys and the signed zone, rerun first boot, then start the services:

sudo systemctl stop unbound unbound-auth
sudo rm -rf /var/lib/unbound-dnssec/
sudo rm /etc/unbound/zones/secure.test.zone /etc/unbound/secure.test.ds
sudo systemctl restart sushi-unbound-firstboot
sudo systemctl start unbound-auth unbound

Other names are not affected.

A service is not running after boot¶

Cause: first boot failed, or a configuration change does not pass its check.

Fix: read the logs:

systemctl status sushi-unbound-firstboot unbound-auth unbound --no-pager
sudo journalctl -b -u sushi-unbound-firstboot -u unbound-auth -u unbound --no-pager

Run sudo unbound-checkconf after any edit. First boot never overwrites an existing configuration, signed zone or key, and it refuses to continue if state paths have been replaced with links. Restore those files from your backup as regular files rather than working around the check.