Confused about the DNS Configuration in OPNsense?
Photo by Maxxa_Satori from iStock
Table of Contents
There are a number of places in OPNsense where you may configure various DNS options. Some of the options apply to the OPNsense system itself while others apply to the Unbound DNS and DHCP services.
In an attempt to bring clarity to the topic, I will discuss the DNS configuration option that are available so you will know when you may or may not want to use them. Since certain options function differently when other options are enabled, I will describe what occurs in each scenario in detail in the sections below.
Note
To say the ‘DNS configuration can be confusing’ is an understatement. I had a difficult time attempting to describe all the scenarios in a way that can be easily digested. There may be room for improvement in this area in the future.
Also after some detailed testing while writing on this topic, I learned some new things about how the DNS options affect DNS resolution on OPNsense and the network.
System > General
The “System > General” may be one of the first pages you will see DNS configuration in OPNsense especially since the OPNsense wizard that runs after a new installation will present you with the options found on this page. As these settings are categorized under the “system” settings, these DNS options pertain to OPNsense itself and the services which run on OPNsense.
DNS Servers List
The “DNS servers” section allows you to specify DNS servers that are used by the OPNsense system when it needs to do lookups to check for and download updates, for instance. If you look at the footnote, it states that the servers are also used for the DHCP and DNS services.
However, the behavior is different depending upon whether or not Unbound DNS is enabled or not. To help illustrate the differences, below describes what occurs in each scenario.
Unbound DNS Enabled:
- Unbound DNS service: If the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option is enabled and the DNS server list is populated, the Unbound DNS service will use the servers in the DNS server list and the DNS servers provided by the DHCP service on the WAN interface. If the DNS server list is empty, the Unbound DNS service will only use the DNS servers provided by DHCP on the WAN interface.
- Unbound DNS service: If the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option is disabled and the DNS server list is populated, the Unbound DNS service will only use the servers in the DNS servers list as the upstream DNS servers. If the DNS server list is empty, the Unbound DNS service will recursively resolve DNS queries (originally I tested this in a virtual machine behind my primary OPNsense router and the lookups failed– most likely that was due to having a recursive resolver behind another recursive resolver).
- DHCP clients: Client devices on the network will use Unbound DNS as their DNS server (each interface’s IP address). Clients do not directly use the DNS servers in the list on the “System > Settings > General” page when Unbound DNS is enabled. This fact is stated at the bottom of the “Services > Unbound DNS > General” page.
- OPNsense system: If the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option is enabled and the DNS server list is populated, the OPNsense system will use localhost (which uses the Unbound DNS service), the servers in the DNS server list, and the DNS servers provided by the DHCP service on the WAN interface. I discovered this to be the case when doing DNS lookups from the OPNsense system on the “Interfaces > Diagnostics > DNS Lookup” page. If the DNS server list is empty, the OPNsense system only uses localhost and the DNS servers provided by the DHCP service on the WAN interface.
- OPNsense system: If the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option is disabled and the DNS server list is populated, the OPNsense system will use localhost (which uses the Unbound DNS service), and the servers in DNS list. If the DNS server list is empty, the OPNsense system will recursively resolve DNS queries (as stated earlier, I was testing in a VM behind my primary OPNsense router so I had a recursive resolver behind another recursive resolver which likely caused problems).
Unbound DNS Disabled:
- DHCP clients: Clients using DHCP will be assigned the DNS servers in the list on the “System > Settings > General” page for DNS lookups rather than each interface’s IP address since Unbound DNS is disabled (even if the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option is enabled).
- DHCP clients: If the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option is enabled and the DNS server list is empty, no DNS server will be assigned to the DHCP clients. This is stated in the tooltip for this option. Only the servers listed in the DNS server list will be used by DHCP clients when Unbound DNS is disabled.
- OPNsense system: If the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option is enabled and the DNS server list is populated, the OPNsense system will use both the DNS servers provided by DHCP on the WAN interface and the DNS servers on the “System > Settings > General” page. If the DNS server list is empty, the OPNsense system will only use the DNS servers provided by DHCP on the WAN interface.
- OPNsense system: If the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option is disabled and the DNS server list is populated, only the DNS servers in the list will be used by the OPNsense system. If the DNS server list is empty, the OPNsense system will not use any DNS servers and DNS lookups will fail.
‘Allow DNS Server List to be Overridden by DHCP’ Option
When discussing the “DNS servers” list in the previous section, I made frequent mention of the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option since it changes the behavior of the DNS lookups performed by OPNsense, Unbound DNS, and DHCP clients.
The biggest surprise to me was that when this option is enabled it still uses the servers listed in the DNS list if it is populated. Based on the name of the option and the description in the tooltip, I originally thought this option would replace the DNS servers list entirely with the DNS servers provided by DHCP on the WAN interface.
Instead, this option seems to prefer the DNS servers provided by the WAN interface while also using any DNS servers in the list on the “System > Settings > General” page.
Of course, if you do not have any DNS servers specified in the list, it will only use the DNS servers provided by the WAN interface. This behavior is similar to consumer grade routers.
‘Do not use the Local DNS Service as a Nameserver for the System’ Option
The OPNsense system includes 127.0.0.1 as the first DNS server by default when Unbound DNS is enabled which means the OPNsense system will use the Unbound DNS service for DNS. If you have servers specified in the DNS servers list and/or you have the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option enabled, those DNS servers will be used as well.
If you want the OPNsense system to use only the DNS servers in the list and/or the DNS servers provided by DHCP on the WAN interface, you may check this option. This will prevent the OPNsense system from using the Unbound DNS service for DNS (while the rest of your local network will use the Unbound DNS service).
Services > DHCPv4 > [Interface]
On the DHCPv4 (or DHCPv6) interface pages, you are able to set DNS servers for a particular network. If you wish to use different DNS server(s) for one or more of your local networks, you may enter them on the DHCPv4 (or DHCPv6) interface pages.
One reason for using this DNS configuration would be to use alternate DNS servers on your network such as a Pi-hole DNS server. You can use the DHCP service to assign alternate DNS servers since by default, all of the DHCP clients receive the interface IP address as the DNS server for each network when Unbound DNS is enabled.
Services > Unbound DNS > General
One quick note that I wanted to mention about Unbound DNS is found on the “Services > Unbound DNS > General” page. I have already mentioned it before, but the note at the bottom of the page states that if Unbound DNS is enabled the DHCP service will automatically service the interface IP address to DHCP clients.
This is an important note if you are not familiar with how Unbound DNS and the DHCP services behave when they are enabled.
Services > Unbound DNS > DNS over TLS
The Unbound DNS service can be configured to use DNS over TLS to encrypt DNS lookups.
Just like with other DNS configuration mentioned above, if you have DNS servers specified on the “System > Settings > General” page or the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option is enabled, the OPNsense system will use all of the configured DNS servers.
Because of that fact, if you want all of your outgoing DNS lookups encrypted, you need to leave the DNS servers list blank and do not enable the “Allow DNS server list to be overridden by DHCP/PPP on WAN” option.
Warning
While all of the DNS lookups from the OPNsense system and all clients using the Unbound DNS service will be encrypted, there is still the possibility that some devices/apps will use their own DNS over TLS or DNS over HTTPS implementations so those queries will not use the configured DNS servers.
Services > Unbound DNS > Query Forwarding
Another DNS option that may be helpful is query forwarding. I have encountered a few issues with DNS lookups on OPNsense VM/systems which are behind OPNsense on my main network when testing certain configurations on my lab network.
Enabling query forwarding allows you to have local hostname resolution behind the second router while forwarding DNS queries upstream to your primary network. You may want to use this option if you are having trouble with DNS lookups on a router behind your primary router, and you do not need any advanced DNS configuration for the network(s) attached to the second router.
Conclusion
While the basic concepts of DNS are simple, configuring DNS can be complicated depending on what you are trying to accomplish. Out of the box, OPNsense (including DNS) should function just like a consumer grade router, but you may wish to configure DNS differently depending on your needs or personal goals.
If you decide to deviate from the default configuration in OPNsense, I hope you find this information helpful!
