Configuration¶

This page shows where Unbound's configuration lives, how to check and apply a change, and how to do the two most common things: forward a private zone, and answer queries from other hosts in your VPC.

Where configuration lives¶

Path	What it is
`/etc/unbound/unbound.conf`	The resolver's configuration, written on first boot.
`/etc/unbound/unbound.conf.d/*.conf`	Your own configuration fragments, included by `unbound.conf`.
`/etc/unbound/unbound-auth.conf`	The local authoritative server for the test zones.
`/usr/share/doc/unbound/forward-zone.conf.example`	An example forward zone, not loaded.
`/var/lib/unbound/root.key`	The DNSSEC root trust anchor, kept up to date by Unbound.
`/etc/unbound/zones/secure.test.zone`, `/etc/unbound/secure.test.ds`	The signed test zone and its DS record.
`/var/lib/unbound-dnssec/`	The test zone's private signing keys. `root` only.

First boot writes each configuration file only if it does not exist yet. Your edits are kept across reboots.

Key defaults in unbound.conf:

interface: 127.0.0.1, port: 53, IPv4 only (do-ip6: no).
Clients: everyone refused except 127.0.0.1.
DNSSEC validation on, using /var/lib/unbound/root.key.
One thread, a 16 MiB message cache and a 32 MiB RRset cache, in memory only.
Answers for public names that point to private or link-local addresses are stripped (private-address).
qname-minimisation: no.

Apply a change¶

Prefer a new file in /etc/unbound/unbound.conf.d/ over editing unbound.conf, so your changes stay separate from the defaults.

Check the configuration:
```
sudo unbound-checkconf
```
Apply it. Most changes only need a reload:
```
sudo systemctl reload unbound
```
A change to interface, port or other listener settings needs a restart instead:
```
sudo systemctl restart unbound
```

Forward a private zone¶

To resolve a Route 53 private hosted zone or another internal zone through the Amazon VPC resolver at 169.254.169.253, start from the example:

sudo cp /usr/share/doc/unbound/forward-zone.conf.example \
  /etc/unbound/unbound.conf.d/private-forward.conf
sudo nano /etc/unbound/unbound.conf.d/private-forward.conf

Replace every internal.example. with your zone name. The result looks like this:

server:
  domain-insecure: "corp.example."
  private-domain: "corp.example."

forward-zone:
  name: "corp.example."
  forward-addr: 169.254.169.253

domain-insecure is needed when the private zone is not DNSSEC-signed.
private-domain lets answers in private address ranges through for this zone.

Then check and reload. Forward only the zones you need. Do not forward ..

Answer queries from your VPC¶

By default, only 127.0.0.1 can query the resolver. To serve other hosts:

In /etc/unbound/unbound.conf, keep the loopback listener and add the instance's private address, then allow your client range:
```
  interface: 127.0.0.1
  interface: <private-ip>
  access-control: <client-cidr> allow
```
Check the configuration and restart Unbound.
In the security group, allow UDP and TCP port 53 only from those client ranges.

Do not create an open resolver

Never allow 0.0.0.0/0 in access-control or in the security group. A resolver open to the internet is quickly abused for attacks.

If your clients resolve internal names that point to private addresses, add private-domain for those zones, as in the forwarding example.

Use the resolver for the instance itself¶

Unbound does not change systemd-resolved or /etc/resolv.conf; the instance keeps using the VPC resolver. If you point the instance at Unbound, forward your private zones first, or names in Route 53 private hosted zones stop resolving.

Enable IPv6¶

The resolver listens on IPv4 only. To add IPv6, set do-ip6: yes, add an IPv6 interface and an IPv6 access-control allow rule, then restart.

Remote control¶

unbound-control talks to the resolver over a local socket, /run/unbound/unbound.ctl. Run it with sudo:

sudo unbound-control -c /etc/unbound/unbound.conf status

Do not run unbound-control-setup unless you deliberately move remote control to a TCP listener, which also requires certificates.