User Tools

Site Tools


docs:guide-user:services:dns:unbound

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
docs:guide-user:services:dns:unbound [2018/07/09 06:03]
ericluehrsen1 add hint to DNS over TLS
docs:guide-user:services:dns:unbound [2018/08/25 20:07] (current)
kevinoid Example 2 fix one missed change in my last edit
Line 1: Line 1:
-====== Unbound ======+======= Unbound ​=======
  
 [[https://​www.unbound.net/​|Unbound]] is a validating, recursive, and caching DNS resolver. The C implementation of Unbound is developed and maintained by [[https://​www.nlnetlabs.nl/​|NLnet Labs]]. [[https://​www.unbound.net/​|Unbound]] is a validating, recursive, and caching DNS resolver. The C implementation of Unbound is developed and maintained by [[https://​www.nlnetlabs.nl/​|NLnet Labs]].
  
-OpenWrt uses Dnsmasq for DNS forwarding (and DHCP serving). This works well for many cases. Dependence on the upstream resolver can be cause for concern. It is often provided by the ISP, and some users have switched to public DNS providers. Either way can result in problems due to performance,​ hijacking, trustworthiness,​ or several other reasons. Running a recursive resolver is a solution.+OpenWrt ​base install ​uses Dnsmasq for DNS forwarding (and DHCP serving). This works well for many cases. Dependence on the upstream resolver can be cause for concern. It is often provided by the ISP, and some users have switched to public DNS providers. Either way can result in problems due to performance,​ hijacking, trustworthiness,​ or several other reasons. Running a recursive resolver is a solution.
  
-Releases [[releases:​17.01:​start|LEDE 17.01]] and [[releases:​18.06:​start|OpenWrt 18.06 rc1]] have UCI and LuCI for Unbound ​with features that may be familiar. "How To" are available for integration with either dnsmasq or odhcpd. "How To" are available to configure Unbound as forwarding client of DNS over TLS. These can be found on GitHub within ​[[https://​github.com/​openwrt/​packages|openwrt/​packages]] in Unbound pacakge ​[[https://​github.com/​openwrt/​packages/​blob/​master/​net/​unbound/​files/​README.md|README]].+Releases [[releases:​17.01:​start|LEDE 17.01]] and [[releases:​18.06:​start|OpenWrt 18.06]] have included ​UCI/LuCI for the Unbound [[https://​github.com/​openwrt/​packages|package]] and complete documentation ​in its [[https://​github.com/​openwrt/​packages/​blob/​master/​net/​unbound/​files/​README.md|README]]. The UCI/LuCI features should be familiar to those that have tweaked dnsmasq in the past. "How To" are available for integration with either dnsmasq or odhcpd. "How To" are available to configure Unbound as forwarding client of DNS over TLS.
  
 +===== Chaos Calmer, Unbound, and dnsmasq =====
  
-===== Unbound with Dnsmasq on Chaos Calmer =====+The remainder of this page describes [[releases:​15.05:​start|OpenWrt Chaos Calmer]] (15.05.1) and how to setup Unbound ​combined ​with [[http://​www.thekelleys.org.uk/​dnsmasq/​doc.html|Dnsmasq]]. There are two examples. Example 1 puts dnsmasq and Unbound in serial configuration,​ so dnsmasq responds to all queries ​on #53 and operates almost in default configuration but treats Unbound as the upstream resolver. Example 1 will be preferred by most due to its simplicity. Example 2 puts Unbound and dnsmasq in parallel, so Unbound responds to all queries on #53, but hands off local domain to dnsmasq. Example 2 may reduce lookup delays in heavy use systems, but is more complex to configure.
  
-The remainder of this page describes how to setup Unbound combined with [[http://​www.thekelleys.org.uk/​dnsmasq/​doc.html|Dnsmasq]] for local name and address resolution on [[releases:​15.05:​start|OpenWrt ​Chaos Calmer]] ​(15.05.1). There are two examples. Example 1 puts dnsmasq and Unbound in serial configuration,​ so dnsmasq responds to all queries ​on #53 and operates almost in default configuration but treats Unbound ​as the upstream resolverExample 1 will be preferred by most due to its simplicityExample 2 puts Unbound and dnsmasq ​in parallel, so Unbound responds to all queries on #53, but hands off local domain to dnsmasqExample 2 may reduce lookup delays in heavy use systems, but is more complex to configure.+The following steps assume that OpenWrt ​CC (15.01has been installed ​on a device ​and configured ​as desired, including ​the network configurationThe later steps require accessing the device using a terminalNote in examples that the choice of local host port 53535 is arbitrarySimilar tutorials often use 5353 or 5355. These may conflict with MDNS). Adjust as desired.
  
- +==== Example 1 - Serial, dnsmasq first and Unbound second ====
-===== Prerequisites ===== +
- +
-The following steps assume that OpenWrt has been installed on a device and +
-configured as desired, including the network configuration. +
- +
-The later steps require accessing the device using a terminal. ​  +
- +
-Note in examples that the choice of local host port 53535 is arbitrary. Similar tutorials often use 5353 or 5355 (which can conflict with MDNS). Adjust as desired. +
- +
- +
-===== Example 1 - Serial, dnsmasq first and Unbound second ​=====+
  
 This should be the preferred configuration for MOST people for several reasons: 1) it's simpler to troubleshoot,​ 2) the configuration is easier, 3) It's faster for local resolution, 4) better for adblocking (dnsmasq has simpler syntax). It puts dnsmasq at port 53, and unbound at 53535. As before, you will need to install unbound by first updating the package list via luci or ''​opkg update'',​ then ''​opkg install unbound'',​ and if you want, ''​opkg install luci-app-unbound''​ This should be the preferred configuration for MOST people for several reasons: 1) it's simpler to troubleshoot,​ 2) the configuration is easier, 3) It's faster for local resolution, 4) better for adblocking (dnsmasq has simpler syntax). It puts dnsmasq at port 53, and unbound at 53535. As before, you will need to install unbound by first updating the package list via luci or ''​opkg update'',​ then ''​opkg install unbound'',​ and if you want, ''​opkg install luci-app-unbound''​
  
- +=== /​etc/​unbound/​unbound.conf ===
-==== /​etc/​unbound/​unbound.conf ​====+
 You can use the default package install configuration for Unbound (small memory), and you only need to change ''​port:​ 53535''​ option. In such configuration Unbound will recurs the global DNS system, but with a lot of users, it could stress a small router. The remaining Unbound example here uses ssl for upstream servers. If you want to use ''​8.8.8.8''​ or other non-tls server, then you need to comment out the ''​ssl-upstream:​ yes''​ line. Adjust as needed. You can use the default package install configuration for Unbound (small memory), and you only need to change ''​port:​ 53535''​ option. In such configuration Unbound will recurs the global DNS system, but with a lot of users, it could stress a small router. The remaining Unbound example here uses ssl for upstream servers. If you want to use ''​8.8.8.8''​ or other non-tls server, then you need to comment out the ''​ssl-upstream:​ yes''​ line. Adjust as needed.
  
Line 69: Line 58:
     forward-addr:​ 149.112.112.112@853 # quad9.net secondary     forward-addr:​ 149.112.112.112@853 # quad9.net secondary
  
- +=== /​etc/​config/​dnsmasq ===
-==== /​etc/​config/​dnsmasq ​====+
 There are TWO changes being made to dnsmasq: 1) add a server option to point to unbound at ''​127.0.0.1#​53535'',​ and to ignore whatever'​s in ''/​etc/​resolv.conf''​ using ''​option noresolv 1'':​ There are TWO changes being made to dnsmasq: 1) add a server option to point to unbound at ''​127.0.0.1#​53535'',​ and to ignore whatever'​s in ''/​etc/​resolv.conf''​ using ''​option noresolv 1'':​
  
Line 90: Line 78:
         list server '​127.0.0.1#​53535'​         list server '​127.0.0.1#​53535'​
  
-==== OPTIONAL ​for adblocking:/​etc/​dnsmasq.conf ​====+=== Option ​for adblocking: /​etc/​dnsmasq.conf ===
 If you want adblocking, dnsmasq accepts wildcards which is better than hosts files because you can cover an entire domain with one line. So: here we point dnsmasq to get our blacklists from the adblock folder. Thus, unbound NEVER has to resolve ad servers. Replace ''​192.168.1.1''​ with the LAN address of your router if different. See the dnsmasq for an explanation of these options if unsure. If you want adblocking, dnsmasq accepts wildcards which is better than hosts files because you can cover an entire domain with one line. So: here we point dnsmasq to get our blacklists from the adblock folder. Thus, unbound NEVER has to resolve ad servers. Replace ''​192.168.1.1''​ with the LAN address of your router if different. See the dnsmasq for an explanation of these options if unsure.
  
Line 99: Line 87:
 You will need to add your blacklist files to the ''/​etc/​adblock''​ folder. These files would contain, for example, lines like ''​address=/​.adserver.com/​0.0.0.0''​. Many adblock list sites will create these dnsmasq-specific blacklist files for you, and in the proper format to be placed in this folder. If the adlist ops to use '​server='​ instead of ''​address='',​ then replace with ''​address=''​. ''​server=''​ redirects address lookups, whereas ''​address=''​ simply serves up the address. You will need to add your blacklist files to the ''/​etc/​adblock''​ folder. These files would contain, for example, lines like ''​address=/​.adserver.com/​0.0.0.0''​. Many adblock list sites will create these dnsmasq-specific blacklist files for you, and in the proper format to be placed in this folder. If the adlist ops to use '​server='​ instead of ''​address='',​ then replace with ''​address=''​. ''​server=''​ redirects address lookups, whereas ''​address=''​ simply serves up the address.
  
- +==== Example 2 - Parallel, Unbound primary and dnsmasq only local  ====
-===== Example 2 - Parallel, Unbound primary and dnsmasq only local  ​=====+
  
 This example directs dns queries to unbound first, then to dnsmasq if local using 'stub zones'​. The installation and configuration instructions below are written in the form of a shell script for precision and clarity to a technical audience. The script can be saved and executed, although it is recommended to run commands and make edits individually both for better understanding and because the script is written to favor readability and clarity of instruction at the cost of thorough error handling and robustness. This example directs dns queries to unbound first, then to dnsmasq if local using 'stub zones'​. The installation and configuration instructions below are written in the form of a shell script for precision and clarity to a technical audience. The script can be saved and executed, although it is recommended to run commands and make edits individually both for better understanding and because the script is written to favor readability and clarity of instruction at the cost of thorough error handling and robustness.
Line 117: Line 104:
   # Note the LAN network address (Network -> Interfaces -> LAN -> IPv4 address)   # Note the LAN network address (Network -> Interfaces -> LAN -> IPv4 address)
   lan_address=$(uci get network.lan.ipaddr)   lan_address=$(uci get network.lan.ipaddr)
 +  ​
 +  # Configure Unbound from unbound.conf,​ instead of generating it from UCI
 +  # Services -> Recursive DNS -> Manual Conf
 +  uci set '​unbound.@unbound[0].manual_conf=1'​
   ​   ​
   # Update the package list (System -> Software -> Update lists)   # Update the package list (System -> Software -> Update lists)
Line 180: Line 171:
   sed -i "/​^server:/​a\ domain-insecure:​ \"​$lan_rdns_domain\""​ /​etc/​unbound/​unbound.conf   sed -i "/​^server:/​a\ domain-insecure:​ \"​$lan_rdns_domain\""​ /​etc/​unbound/​unbound.conf
   ​   ​
-  # Add a stub zone to dnsmasq ​for the local domain to the unbound configuration +  # Add a forward ​zone for the local domain to forward requests to dnsmasq 
-  cat >> /​etc/​unbound/​unbound.conf <<DNS_STUB_ZONE +  cat >> /​etc/​unbound/​unbound.conf <<DNS_FORWARD_ZONE 
-  ​stub-zone:+  ​forward-zone:
   name: "​$lan_domain"​   name: "​$lan_domain"​
-  stub-addr: 127.0.0.1@53535 +  forward-addr: 127.0.0.1@53535 
-  ​DNS_STUB_ZONE+  ​DNS_FORWARD_ZONE
   ​   ​
-  # Add a stub zone to dnsmasq ​for the local reverse domain to unbound.conf +  # Add a forward ​zone for the local reverse domain to forward requests to dnsmasq 
-  cat >> /​etc/​unbound/​unbound.conf <<RDNS_STUB_ZONE +  cat >> /​etc/​unbound/​unbound.conf <<RDNS_FORWARD_ZONE 
-  ​stub-zone:+  ​forward-zone:
   name: "​$lan_rdns_domain"​   name: "​$lan_rdns_domain"​
-  stub-addr: 127.0.0.1@53535 +  forward-addr: 127.0.0.1@53535 
-  ​RDNS_STUB_ZONE+  ​RDNS_FORWARD_ZONE
   ​   ​
   # Optionally enable DNS Rebinding protection by uncommenting private-address   # Optionally enable DNS Rebinding protection by uncommenting private-address
Line 220: Line 211:
   private-domain:​ "​example.local"​   private-domain:​ "​example.local"​
   ​   ​
-  ​stub-zone:+  ​forward-zone:
   name: "​example.local"​   name: "​example.local"​
-  stub-addr: 127.0.0.1@53535+  forward-addr: 127.0.0.1@53535
   ​   ​
-  ​stub-zone:+  ​forward-zone:
   name: "​0.168.192.in-addr.arpa"​   name: "​0.168.192.in-addr.arpa"​
-  stub-addr: 127.0.0.1@53535+  forward-addr: 127.0.0.1@53535
  
  
-===== Troubleshooting ​=====+==== Troubleshooting ====
  
 After completing the above steps, DNS should be working for both local and After completing the above steps, DNS should be working for both local and
Line 245: Line 236:
 do a reverse lookup. do a reverse lookup.
  
-==== No Response ​====+=== No Response ===
  
 If Unbound is not responding to any request, try restarting the service with If Unbound is not responding to any request, try restarting the service with
Line 251: Line 242:
 errors ''​logread | tail''​. errors ''​logread | tail''​.
  
-==== Negative Response for Local Only ====+=== Negative Response for Local Only ===
  
 If the local domain or addresses result in negative responses, check that they If the local domain or addresses result in negative responses, check that they
Line 258: Line 249:
 match a predefined zone), and as a ''​name''​ in ''​stub-zone''​. match a predefined zone), and as a ''​name''​ in ''​stub-zone''​.
  
-==== Failures for DNSSEC-Secured Domains ​====+=== Failures for DNSSEC-Secured Domains ===
  
 If domains which use DNSSEC fail to resolve while other domains work, check that the system time is correct. ​ Time skew can cause validation failures. ​ If the time is incorrect, check the [[docs:​guide-user:​services:​ntp:​client-server|NTP client configuration]]. If domains which use DNSSEC fail to resolve while other domains work, check that the system time is correct. ​ Time skew can cause validation failures. ​ If the time is incorrect, check the [[docs:​guide-user:​services:​ntp:​client-server|NTP client configuration]].
  
-===== Further Additions ===== +=== IPv6 ===
- +
-==== IPv6 ===+
- +
-It is relatively straightforward to extend the above configuration for IPv6. Forward resolution (from local domain to IPv6 address) does not require any +
-additional changes to Unbound, although it may require configuration changes to Dnsmasq. ​ See [[docs:​guide-user:​network:​ipv6:​ipv6.dns|IPv6 DNS]].+
  
-To configure reverse DNS for IPv6:  Determine the rDNS domain from the IPv6 address prefix by reversing the nibbles and appending "​.ip6.arpa",​ add ''​domain-insecure:​ $lan6_rdns_domain'',​ ''​local-zone:​ $lan6_rdns_domain nodefault''​ if it is in a private range (be sure to use a [[https://​www.unbound.net/​documentation/​unbound.conf.html|preconfigured range]]), and add ''​stub-zone''​ with ''​name:​ "​$lan6_rdns_domain"''​ in the same way as ''​$lan_rdns_domain''​ above.+It is relatively straightforward to extend the above configuration for IPv6. Forward resolution (from local domain to IPv6 address) does not require any additional changes to Unbound, although it may require configuration changes to Dnsmasq. ​ See [[docs:​guide-user:​network:​ipv6:​ipv6.dns|IPv6 DNS]]. ​To configure reverse DNS for IPv6:  Determine the rDNS domain from the IPv6 address prefix by reversing the nibbles and appending "​.ip6.arpa",​ add ''​domain-insecure:​ $lan6_rdns_domain'',​ ''​local-zone:​ $lan6_rdns_domain nodefault''​ if it is in a private range (be sure to use a [[https://​www.unbound.net/​documentation/​unbound.conf.html|preconfigured range]]), and add ''​stub-zone''​ with ''​name:​ "​$lan6_rdns_domain"''​ in the same way as ''​$lan_rdns_domain''​ above.
docs/guide-user/services/dns/unbound.1531116205.txt.gz · Last modified: 2018/07/09 06:03 by ericluehrsen1