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
Next revisionBoth sides next revision
docs:guide-user:services:dns:unbound [2018/04/01 19:01] – [OPTIONAL for adblocking:/etc/dnsmasq.conf] jaf323docs:guide-user:services:dns:unbound [2021/02/27 10:23] – Added link to forum for WIP How to for Snapshot doppel-d
Line 1: Line 1:
-====== Unbound with Dnsmasq on Chaos Calmer ======+======= 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]].
  
-This page describes how to setup [[https://www.unbound.net/|Unbound]] as a +OpenWrt base install uses Dnsmasq for DNS forwarding (and DHCP serving)This works well for many casesDependence on the upstream resolver can be cause for concernIt 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 reasonsRunning a recursive resolver is a solution.
-validating, recursive, caching DNS resolver combined with +
-[[http://www.thekelleys.org.uk/dnsmasq/doc.html|Dnsmasq]] for local +
-name and address resolution on OpenWRT Chaos Calmer (15.05.1)There are two examples: Example 1 replaces dnsmasq with unbound as the default responder on port 53, and Example 2 keeps dnsmasq as the first responder, who can then do adblocking/local address lookups before handing over to unbound if the address isn't localExample 2 should be preferred for most people for the reasons outlined below.+
  
-In upcoming releases it appears that Unbound will be much better integrated +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 README. 
-and most of the configuration in this page will be unnecessary If so, refer +The UCI/LuCI features should be familiar to those that have tweaked dnsmasq in the past. 
-to the [[docs:guide-user:base-system:dhcp|DNS and DHCP configuration]] pages.+"How To" are available for integration with either dnsmasq or odhcpd. 
 +"How To" are available to configure Unbound as forwarding client of DoT.
  
 +DNS over TLS is fully supported with Unbound configuration helpers in UCI and LuCI. **You should be able to find it all in the README.** You can manage zone recursion, zone forward, and zone transfer preferences. These are present in a form similar to how the firewall pin point rules work. You may forward specific domains to specific DNS servers with or without TLS. This may be useful where you need location specific resolution for ISP colocated services such as is often done by Google (www.youtube.com by 8.8.8.8), but wish to have a private DNS like CloudFlare (1.1.1.1) mask location while resolving general look-ups.
 +WIP "How To" for Snapshot on the [[https://forum.openwrt.org/t/dns-privacy-aka-dns-over-tls-for-openwrt-updated-w-bonus-videos-for-setup-and-verification/89772|forum]]
  
-===== Why Unbound? ===== +Documentation
- +  [[https://github.com/openwrt/packages/tree/lede-17.01/net/unbound/files/README.md|README for Unbound 1.6.8 @ LEDE 17.01]] 
-By default, OpenWRT uses Dnsmasq for DNS forwarding (and DHCP serving).  This +  * [[https://github.com/openwrt/packages/tree/openwrt-18.06/net/unbound/files/README.md|README for Unbound 1.10.1 @ OpenWrt 18.06]] 
-works well for most cases.  One notable issue is that it requires a separate +  * [[https://github.com/openwrt/packages/tree/openwrt-19.07/net/unbound/files/README.md|README for Unbound 1.10.1 @ OpenWrt 19.07]] 
-recursive DNS resolver, usually provided by an ISP or public DNS provider, to +  [[https://github.com/openwrt/packages/tree/master/net/unbound/files/README.md|README for Unbound OpenWrt Snapshot]]
-resolve requests.  This can be a problem due to performance, hijacking, +
-trustworthiness, or several other reasons.  Running a recursive resolver, such +
-as unbound, is a solution. +
- +
- +
-===== 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.   +
- +
- +
-====== Installation and Configuration Example 1 (Unbound first, dnsmasq second) ====== +
- +
-This example directs dns queries to unbound first, then to dnsmasq if local using 'stub zones'. See the second example if you want dnsmasq to be first. +
-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. +
- +
-Note that the choice of port 53535 is arbitrary.  Similar tutorials often use +
-5353 or 5355 (which can conflict with MDNS).  Adjust as desired. +
- +
-  #!/bin/sh +
-  # Steps to configure unbound on OpenWRT with dnsmasq for dynamic DNS +
-  # Note Clarity of instruction is favored over script speed or robustness. +
-  #        It is not idempotent. +
-   +
-  # Show commands as executed, error out on failure or undefined variables +
-  set -eux +
-   +
-  # Note the local domain (Network -> DHCP & DNS -> General Settings) +
-  lan_domain=$(uci get 'dhcp.@dnsmasq[0].domain'+
-   +
-  # Note the LAN network address (Network -> Interfaces -> LAN -> IPv4 address) +
-  lan_address=$(uci get network.lan.ipaddr) +
-   +
-  # Update the package list (System -> Software -> Update lists) +
-  opkg update +
-   +
-  # Install unbound (System -> Software -> Find package: unbound -> Install) +
-  opkg install unbound # Ignore error that it can't listen on port 53 +
-   +
-  # Move dnsmasq to port 53535 where it will still serve local DNS from DHCP +
-  # Network -> DHCP & DNS -> Advanced Settings -> DNS server port to 53535 +
-  uci set 'dhcp.@dnsmasq[0].port=53535' +
-   +
-  # Configure dnsmasq to send a DNS Server DHCP option with its LAN IP +
-  # since it does not do this by default when port is configured. +
-  uci add_list "dhcp.lan.dhcp_option=option:dns-server,$lan_address" +
-   +
-  # Save & Apply (will restart dnsmasq, DNS unreachable until unbound is up) +
-  uci commit +
-   +
-  # Allow unbound to query dnsmasq on the loopback address +
-  # by adding 'do-not-query-localhost: no' to server section +
-  sed -i '/^server:/a\ do-not-query-localhost: no' /etc/unbound/unbound.conf +
-   +
-  # Convert the network address to a Reverse DNS domain +
-  # https://en.wikipedia.org/wiki/Reverse_DNS_lookup +
-  case $(uci get network.lan.netmask) in +
-      255.255.255.0) ip_to_rdns='\3.\2.\1.in-addr.arpa' ;; +
-      255.255.0.0) ip_to_rdns='\2.\1.in-addr.arpa' ;; +
-      255.0.0.0) ip_to_rdns='\1.in-addr.arpa' ;; +
-      *) echo 'More complex rDNS configuration required.' >&2 ; exit 1 ;; +
-  esac +
-  lan_rdns_domain=$(echo "$lan_address" | \ +
-      sed -E "s/^([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+)$/$ip_to_rdns/") +
-   +
-  # Check if the local addresses are in a private address range (very common) +
-  case "$lan_address" in +
-      0.*) ip_to_priv_rdns='0.in-addr.arpa.' ;; +
-      10.*) ip_to_priv_rdns='10.in-addr.arpa.' ;; +
-      169.254.*) ip_to_priv_rdns='254.169.in-addr.arpa.' ;; +
-      172.1[6-9].*|172.2[0-9].*|172.3[0-1].*) ip_to_priv_rdns='\2.172.in-addr.arpa.' ;; +
-      192.0.2.*) ip_to_priv_rdns='2.0.192.in-addr.arpa.' ;; +
-      192.168.*) ip_to_priv_rdns='168.192.in-addr.arpa.' ;; +
-      198.51.100.*) ip_to_priv_rdns='100.51.198.in-addr.arpa.' ;; +
-      203.0.113.*) ip_to_priv_rdns='113.0.203.in-addr.arpa.' ;; +
-  esac +
-  if [ -n "${ip_to_priv_rdns-}" ] ; then +
-      # Disable default "does not exist" reply for private address ranges +
-      # by adding 'local-zone "$lan_domain" nodefault' to server section +
-      # Note that this must be on RFC 1918/5735/5737 boundary, +
-      # this is only equal to $lan_rdns_domain when netmask covers whole range. +
-      lan_priv_rdns_domain=$(echo "$lan_address" | \ +
-          sed -E "s/^([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+)$/$ip_to_priv_rdns/") +
-      sed -i "/^server:/a\ local-zone: \"$lan_priv_rdns_domain\" nodefault" +
-          /etc/unbound/unbound.conf +
-  fi +
-   +
-  # Ignore DNSSEC chain of trust for the local domain +
-  # by adding 'domain-insecure: "$lan_domain"' to server section +
-  sed -i "/^server:/a\ domain-insecure: \"$lan_domain\"" /etc/unbound/unbound.conf +
-   +
-  # Ignore DNSSEC chain of trust for the local reverse domain +
-  # by adding 'domain-insecure: "$lan_rdns_domain"' to server section +
-  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 +
-  cat >> /etc/unbound/unbound.conf <<DNS_STUB_ZONE +
-  stub-zone: +
-  name: "$lan_domain" +
-  stub-addr: 127.0.0.1@53535 +
-  DNS_STUB_ZONE +
-   +
-  # Add a stub zone to dnsmasq for the local reverse domain to unbound.conf +
-  cat >> /etc/unbound/unbound.conf <<RDNS_STUB_ZONE +
-  stub-zone: +
-  name: "$lan_rdns_domain" +
-  stub-addr: 127.0.0.1@53535 +
-  RDNS_STUB_ZONE +
-   +
-  # Optionally enable DNS Rebinding protection by uncommenting private-address +
-  # configuration and adding 'private-domain: "$lan_domain"' to server section +
-  sed -E -i \ +
-      -e 's/(# )?private-address:/private-address:/' \ +
-      -e "/^server:/a\ private-domain: \"$lan_domain\""+
-      /etc/unbound/unbound.conf +
-   +
-  # Restart (or start) unbound (System -> Startup -> unbound -> Restart) +
-  /etc/init.d/unbound restart +
- +
-The resulting configuration (with defaults and comments removed) should look +
-something like: +
- +
-  server: +
-  do-not-query-localhost: no +
-  domain-insecure: "0.168.192.in-addr.arpa" +
-  domain-insecure: "example.local" +
-  local-zone: "168.192.in-addr.arpa." nodefault +
-  private-address: 10.0.0.0/+
-  private-address: 169.254.0.0/16 +
-  private-address: 172.16.0.0/12 +
-  private-address: 192.168.0.0/16 +
-  private-address: fd00::/8 +
-  private-address: fe80::/10 +
-  private-domain: "example.local" +
-  stub-zone: +
-  name: "example.local" +
-  stub-addr: 127.0.0.1@53535 +
-  stub-zone: +
-  name: "0.168.192.in-addr.arpa" +
-  stub-addr: 127.0.0.1@53535 +
- +
- +
-===== Troubleshooting ===== +
- +
-After completing the above steps, DNS should be working for both local and +
-global addresses.  If not, here are some suggested troubleshooting steps: +
- +
-Resolution can be attempted from the OpenWRT system by running +
-''nslookup openwrt.org 127.0.0.1'' and +
-''nslookup openwrt.org 127.0.0.1:53535''+
-Unfortunately, the nslookup output does not distinguish between no response and +
-a negative response, which significantly reduces its usefulness for debugging. +
-A much more powerful lookup tool is DiG from the +
-''bind-dig'' package.  To use it run +
-''dig openwrt.org @127.0.0.1'', add ''-p 53535'' to query +
-the Dnsmasq port, or add ''-x'' with an IP in place of the domain to +
-do a reverse lookup. +
- +
-==== No Response ==== +
- +
-If Unbound is not responding to any request, try restarting the service with +
-''/etc/init.d/unbound restart'' and checking the system log for +
-errors ''logread | tail''+
- +
-==== Negative Response for Local Only ==== +
- +
-If the local domain or addresses result in negative responses, check that they +
-are resolved correctly by Dnsmasq on port 53535.  If so, check that the domain +
-appears in ''domain-insecure'', ''local-zone'' (which may be a suffix and must +
-match a predefined zone), and as a ''name'' in ''stub-zone''+
- +
-==== 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]]. +
-===== Further Additions ===== +
- +
-==== 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. +
- +
-====== Installation and Configuration Example 2 (dnsmasq first, 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'' +
-===== /etc/config/unbound ===== +
-Note that we're putting unbound at port 53535, and doing ip4 lookups only to speed things up. In addition, we want some customization so the manual_conf flag is set to 1. +
- +
-  config unbound +
-        option add_local_fqdn '1' +
-        option add_wan_fqdn '0' +
-        option dhcp_link 'none' +
-        option dhcp4_slaac6 '0' +
-        option dns64 '0' +
-        option domain 'lan' +
-        option domain_type 'static' +
-        option edns_size '1280' +
-        option hide_binddata '1' +
-        option localservice '1' +
-        option query_minimize '0' +
-        option rebind_protection '1' +
-        option recursion 'passive' +
-        option resource 'small' +
-        option root_age '9' +
-        option ttl_min '120' +
-        option unbound_control '0' +
-        option validator '0' +
-        option enabled '1' +
-        option rebind_localhost '1' +
-        option listen_port '53535' +
-        option protocol 'ip4_only' +
-        option manual_conf '1' +
- +
-=====/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'': +
- +
-        option domainneeded '1' +
-        option boguspriv '1' +
-        option localise_queries '1' +
-        option rebind_protection '1' +
-        option rebind_localhost '1' +
-        option local '/lan/' +
-        option domain 'lan' +
-        option expandhosts '1' +
-        option authoritative '1' +
-        option readethers '1' +
-        option leasefile '/tmp/dhcp.leases' +
-        option resolvfile '/tmp/resolv.conf.auto' +
-        option localservice '1' +
-        # The following redirects dns to unbound +
-        option noresolv '1' +
-        list server '127.0.0.1#53535' +
- +
-=====OPTIONAL 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. +
- +
-  listen-address=127.0.0.1,192.168.1.1 +
-  bind-interfaces +
-  conf-dir=/etc/adblock/,*.conf +
- +
-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. +
-=====/etc/unbound/unbound.conf===== +
-This configuration 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. There are other options that probably could be done in UCI, but many unbound examples refer to the ''unbound.conf'' file so it's easier to just use unbound's own configurations. Also: this configuration makes unbound friendlier for a home router in terms of resource consumption. Adjust as needed. +
- +
-  server: +
-    port: 53535 +
-    access-control: 10.0.0.0/8 allow +
-    access-control: 127.0.0.0/8 allow +
-    access-control: 192.168.0.0/16 allow +
-    cache-max-ttl: 14400 +
-    cache-min-ttl: 900 +
-    do-tcp: yes +
-    hide-identity: yes +
-    hide-version: yes +
-    interface: 0.0.0.0 +
-    minimal-responses: yes +
-    prefetch: yes +
-    qname-minimisation: yes +
-    rrset-roundrobin: yes +
-    ssl-upstream: yes +
-    use-caps-for-id: yes +
-    verbosity: 1 +
-    do-ip4: yes +
-    do-ip6: no +
-    outgoing-port-permit: "10240-65335" +
-    outgoing-range: 60 +
-    num-queries-per-thread: 30 +
-    msg-buffer-size: 8192 +
-    infra-cache-numhosts: 200 +
-    msg-cache-size: 100k +
-    rrset-cache-size: 100k +
-    key-cache-size: 100k +
-    neg-cache-size: 10k +
-    target-fetch-policy: "2 1 0 0 0 0" +
-    harden-large-queries: yes +
-    harden-short-bufsize: yes +
-  forward-zone: +
-    name: "." +
-    forward-addr: 9.9.9.9@853         # quad9.net primary +
-    forward-addr: 149.112.112.112@853 # quad9.net secondary+
  
 +Note there are significant options enhancements from 18.06 to 19.07 including UCI/LuCI for TLS.
  
  • Last modified: 2021/03/02 17:13
  • by doppel-d