DNS Resolver Configuration

To configure the DNS Resolver, navigate to Services > DNS Resolver

DNS Resolver Options

Enable:

Controls whether or not the DNS Resolver is enabled. Check the box to enable the DNS Resolver service, uncheck to disable the service.

Two DNS services cannot both be active at the same time on the same ports. This includes, but is not limited to, the DNS Resolver, the DNS Forwarder, and the BIND package. Ensure other services are disabled or moved to different ports before attempting to enable the DNS Resolver.

Listen Port:

The TCP and UDP port on which the DNS Resolver will listen for queries from clients. By default this is port 53. This is the normal port for any DNS server, as it is the port expected by clients.

Certain use cases may involve moving the DNS Resolver to another Listen Port, such as 5353 or 54, and then specific sources may be forwarded there via port forwards.

Enable SSL/TLS Service:

Configures the DNS Resolver to act as a DNS over TLS server which can answer queries from DNS over TLS clients.

Note

Activating this option disables automatic interface response routing behavior, thus it works best with specific interface bindings.

SSL/TLS Certificate:

The server certificate to use when acting as an SSL/TLS server.

For clients to properly validate the server, they must trust this certificate. One way to accomplish that easily is to use a certificate generated by the ACME package.

SSL/TLS Listen Port:

The TCP and UDP port on which the DNS Resolver will listen for queries from DNS over TLS clients. By default this is port 853.

Network Interfaces:

The network interface(s) to which the DNS Resolver will bind when listening for queries from clients.

By default the DNS Resolver listens on every available interface and IPv4 and IPv6 address. This option limits the interfaces where the DNS Resolver will accept and answer queries. This can be used to increase security in addition to firewall rules.

If specific interfaces are selected, both the IPv4 and IPv6 addresses on those interfaces will be used for answering queries. Additionally, The unbound daemon will only bind to the selected interfaces. Queries sent to other IP addresses on the firewall will be silently discarded.

Outgoing Network Interfaces:

Controls which interfaces the firewall will utilize when sending its own queries to other DNS servers.

By default the DNS Resolver utilizes all interfaces for outbound queries so it will source the query from whichever interface and IP address is closest to the target server from a routing perspective. Selecting specific interfaces will limit the choices to only specific interfaces that may be used as a source of queries.

System Domain Local Zone Type:

This option determines the type of local-zone configured in unbound for the system domain. The zone type governs the type of response given to clients when there is no match in local data such as Host Overrides, DHCP hosts, etc. In each case, if there is a local match, the query is answered normally. The available types to govern non-matching responses are:

Deny:

Drops the query and does not answer the client.

Refuse:

Notifies the client that the query was refused (Using rcode REFUSED).

Static:

Returns a NODATA or NXDOMAIN response to the client.

Transparent:

This is the default behavior. If the query is for a name that does not exist locally, it is resolved as usual. If the name has a local match but the type is different, a NOERROR, NODATA response is sent to the client

Type Transparent:

Similar to Transparent but it also passes through queries where the name matches but the type does not. For example, if a client queries for an AAAA record but only an A record exists, the AAAA query is passed on rather than resulting in a negative response.

Redirect:

Handles queries from local data and redirects queries for zones underneath the local zone (e.g. subdomains). This can be used to control queries for all subdomains under the given domain.

Inform:

Answers normally, but logs the client query.

Inform Deny:

Denies and logs the query.

No default:

Disables any default content for the zone without affecting query behavior.

DNSSEC:

Enables Domain Name System Security Extensions (DNSSEC), which allows clients to trust the origin and content of DNS responses. This is enabled by default.

DNSSEC protects against manipulation of DNS responses, such as DNS cache poisoning or other query interception, but it does not make the contents of responses secret.

DNSSEC works best when using the root servers directly, unless the forwarding servers support DNSSEC. Even if the forwarding DNS servers support DNSSEC, the response cannot be fully validated.

If upstream DNS servers do not support DNSSEC in forwarding mode or with domain overrides, DNS queries are known to be intercepted upstream, or clients have issues with large DNS responses, DNSSEC may need to be disabled.

Python Module:

Enables the DNS Resolver Python module. This feature utilizes a Python script to act on queries or results. For example, a script could prevent certain domains or record type combinations from being resolved.

Python Module Order:

Controls the position of the Python module in the DNS resolution process. If DNSSEC is disabled, this option has no effect.

Pre Validator:

The script is run before DNSSEC validation.

Post Validator:

The script is run after DNSSEC validation.

Python Module Script:

The python script file to execute. The script must be uploaded to the firewall in /var/unbound/. The filename must end in .py.

DNS Query Forwarding:

Controls whether unbound uses resolver mode (unchecked) or forwarding mode (checked). See DNS Resolver Mode for an explanation of the modes.

The default is resolver mode (unchecked).

When checked, unbound will use the system DNS Servers from System > General Setup or those received from a dynamic WAN, rather than using the root servers directly.

Certain situation require or work better with forwarding mode, such as when utilizing DNS over TLS for outgoing queries or for optimal multi-WAN configurations.

Use SSL/TLS for outgoing DNS Queries to Forwarding Servers:

Sends queries to all upstream forwarding DNS servers using SSL/TLS on the default port of 853. Requires DNS Query Forwarding to be checked.

See Configuring DNS over TLS for detailed instructions.

Warning

All upstream forwarding servers must support SSL/TLS queries on port 853.

DHCP Registration:

Controls whether or not internal machine names for DHCP clients are registered in the DNS Resolver. The domain name from System > General Setup is used as the domain name on the hosts.

This feature allows systems using the DNS Resolver as their DNS server to resolve these names using DNS.

Note

This only works for clients that specify a hostname in their DHCP requests.

Warning

The DNS Resolver is reloaded when updating hostnames it learns from DHCP lease data. On busy networks with many DHCP clients, this can result in temporary DNS outages as unbound reloads. In most cases this is only a factor when using add-on packages which increase the burden on the DNS Resolver or which make it take longer than usual to reload.

Static DHCP:

This works the same as Register DHCP leases in DNS resolver, except that it registers the DHCP static mapping addresses.

OpenVPN Client:

Controls whether or not OpenVPN client names are registered in the DNS Resolver.

If this option is set, then the common name (CN) of connected OpenVPN clients will be registered in the DNS Resolver along with the client address inside the VPN. The domain in System > General Setup is used as the domain name on these entries.

Note

This option requires an OpenVPN server to be operating in Remote Access SSL/TLS mode or in User Auth mode with Username as Common Name active.

Custom Options:

A text area for advanced unbound directives not directly supported by the GUI.

Tip

If unbound does not start correctly after entering custom options, add server: on a line at the top of the custom options text area.