Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision | ||
| docs:guide-user:services:dns:unbound [2018/08/10 07:06] – unbound: visual presentation ericluehrsen1 | docs: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 ======= | ======= Unbound ======= | ||
| - | |||
| [[https:// | [[https:// | ||
| 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, | 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, | ||
| - | Releases [[releases: | + | Releases [[releases: |
| - | + | The UCI/LuCI features should be familiar to those that have tweaked dnsmasq in the past. | |
| - | ===== Chaos Calmer, Unbound, and dnsmasq ===== | + | "How To" are available for integration with either dnsmasq or odhcpd. |
| - | + | "How To" are available to configure Unbound as forwarding client of DoT. | |
| - | The remainder of this page describes [[releases: | + | |
| - | + | ||
| - | The following steps assume that OpenWrt CC (15.01) 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. These may 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, | + | |
| - | + | ||
| - | === / | + | |
| - | You can use the default package install configuration for Unbound (small memory), and you only need to change '' | + | |
| - | + | ||
| - | server: | + | |
| - | port: 53535 | + | |
| - | access-control: | + | |
| - | access-control: | + | |
| - | access-control: | + | |
| - | cache-max-ttl: | + | |
| - | cache-min-ttl: | + | |
| - | do-tcp: yes | + | |
| - | hide-identity: | + | |
| - | hide-version: | + | |
| - | interface: 0.0.0.0 | + | |
| - | minimal-responses: | + | |
| - | prefetch: yes | + | |
| - | qname-minimisation: | + | |
| - | rrset-roundrobin: | + | |
| - | ssl-upstream: | + | |
| - | use-caps-for-id: | + | |
| - | verbosity: 1 | + | |
| - | do-ip4: yes | + | |
| - | do-ip6: no | + | |
| - | outgoing-port-permit: | + | |
| - | outgoing-range: | + | |
| - | num-queries-per-thread: | + | |
| - | msg-buffer-size: | + | |
| - | infra-cache-numhosts: | + | |
| - | msg-cache-size: | + | |
| - | rrset-cache-size: | + | |
| - | key-cache-size: | + | |
| - | neg-cache-size: | + | |
| - | target-fetch-policy: | + | |
| - | harden-large-queries: | + | |
| - | harden-short-bufsize: | + | |
| - | + | ||
| - | forward-zone: | + | |
| - | name: " | + | |
| - | forward-addr: | + | |
| - | forward-addr: | + | |
| - | + | ||
| - | === / | + | |
| - | There are TWO changes being made to dnsmasq: 1) add a server option to point to unbound at '' | + | |
| - | + | ||
| - | option domainneeded ' | + | |
| - | option boguspriv ' | + | |
| - | option localise_queries ' | + | |
| - | option rebind_protection ' | + | |
| - | option rebind_localhost ' | + | |
| - | option local '/ | + | |
| - | option domain ' | + | |
| - | option expandhosts ' | + | |
| - | option authoritative ' | + | |
| - | option readethers ' | + | |
| - | option leasefile '/ | + | |
| - | option resolvfile '/ | + | |
| - | option localservice ' | + | |
| - | # The following redirects dns to unbound | + | |
| - | option noresolv ' | + | |
| - | list server ' | + | |
| - | + | ||
| - | === Option for adblocking: / | + | |
| - | 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 '' | + | |
| - | + | ||
| - | listen-address=127.0.0.1, | + | |
| - | bind-interfaces | + | |
| - | conf-dir=/ | + | |
| - | + | ||
| - | You will need to add your blacklist files to the ''/ | + | |
| - | + | ||
| - | ==== 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' | + | |
| - | + | ||
| - | #!/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 ' | + | |
| - | + | ||
| - | # 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 ' | + | |
| - | + | ||
| - | # 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 " | + | |
| - | + | ||
| - | # Save & Apply (will restart dnsmasq, DNS unreachable until unbound is up) | + | |
| - | uci commit | + | |
| - | + | ||
| - | # Allow unbound to query dnsmasq on the loopback address | + | |
| - | # by adding ' | + | |
| - | sed -i '/ | + | |
| - | + | ||
| - | # Convert the network address to a Reverse DNS domain | + | |
| - | # https:// | + | |
| - | case $(uci get network.lan.netmask) in | + | |
| - | 255.255.255.0) ip_to_rdns=' | + | |
| - | 255.255.0.0) ip_to_rdns=' | + | |
| - | 255.0.0.0) ip_to_rdns=' | + | |
| - | *) echo 'More complex rDNS configuration required.' | + | |
| - | esac | + | |
| - | lan_rdns_domain=$(echo " | + | |
| - | sed -E " | + | |
| - | + | ||
| - | # Check if the local addresses are in a private address range (very common) | + | |
| - | case " | + | |
| - | 0.*) ip_to_priv_rdns=' | + | |
| - | 10.*) ip_to_priv_rdns=' | + | |
| - | 169.254.*) ip_to_priv_rdns=' | + | |
| - | 172.1[6-9].*|172.2[0-9].*|172.3[0-1].*) ip_to_priv_rdns=' | + | |
| - | 192.0.2.*) ip_to_priv_rdns=' | + | |
| - | 192.168.*) ip_to_priv_rdns=' | + | |
| - | 198.51.100.*) ip_to_priv_rdns=' | + | |
| - | 203.0.113.*) ip_to_priv_rdns=' | + | |
| - | esac | + | |
| - | if [ -n " | + | |
| - | # Disable default "does not exist" reply for private address ranges | + | |
| - | # by adding ' | + | |
| - | # Note that this must be on RFC 1918/ | + | |
| - | # this is only equal to $lan_rdns_domain when netmask covers whole range. | + | |
| - | lan_priv_rdns_domain=$(echo " | + | |
| - | sed -E " | + | |
| - | sed -i "/ | + | |
| - | / | + | |
| - | fi | + | |
| - | + | ||
| - | # Ignore DNSSEC chain of trust for the local domain | + | |
| - | # by adding ' | + | |
| - | sed -i "/ | + | |
| - | + | ||
| - | # Ignore DNSSEC chain of trust for the local reverse domain | + | |
| - | # by adding ' | + | |
| - | sed -i "/ | + | |
| - | + | ||
| - | # Add a stub zone to dnsmasq for the local domain to the unbound configuration | + | |
| - | cat >> / | + | |
| - | stub-zone: | + | |
| - | name: " | + | |
| - | 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 >> / | + | |
| - | stub-zone: | + | |
| - | name: " | + | |
| - | stub-addr: 127.0.0.1@53535 | + | |
| - | RDNS_STUB_ZONE | + | |
| - | + | ||
| - | # Optionally enable DNS Rebinding protection by uncommenting private-address | + | |
| - | # configuration and adding ' | + | |
| - | sed -E -i \ | + | |
| - | -e 's/(# )? | + | |
| - | -e "/ | + | |
| - | / | + | |
| - | + | ||
| - | # Restart (or start) unbound (System -> Startup -> unbound -> Restart) | + | |
| - | / | + | |
| - | + | ||
| - | The resulting configuration (with defaults and comments removed) should look | + | |
| - | something like: | + | |
| - | + | ||
| - | server: | + | |
| - | do-not-query-localhost: | + | |
| - | domain-insecure: | + | |
| - | domain-insecure: | + | |
| - | local-zone: | + | |
| - | private-address: | + | |
| - | private-address: | + | |
| - | private-address: | + | |
| - | private-address: | + | |
| - | private-address: | + | |
| - | private-address: | + | |
| - | private-domain: | + | |
| - | + | ||
| - | stub-zone: | + | |
| - | name: " | + | |
| - | stub-addr: 127.0.0.1@53535 | + | |
| - | + | ||
| - | stub-zone: | + | |
| - | name: " | + | |
| - | stub-addr: 127.0.0.1@53535 | + | |
| - | + | ||
| - | + | ||
| - | ==== Troubleshooting ==== | + | |
| - | + | ||
| - | After completing the above steps, DNS should be working for both local and | + | |
| - | global addresses. | + | |
| - | + | ||
| - | Resolution can be attempted from the OpenWrt system by running | + | |
| - | '' | + | |
| - | '' | + | |
| - | Unfortunately, | + | |
| - | a negative response, which significantly reduces its usefulness for debugging. | + | |
| - | A much more powerful lookup tool is DiG from the | + | |
| - | '' | + | |
| - | '' | + | |
| - | the Dnsmasq port, or add '' | + | |
| - | do a reverse lookup. | + | |
| - | + | ||
| - | === No Response === | + | |
| - | + | ||
| - | If Unbound is not responding to any request, try restarting the service with | + | |
| - | ''/ | + | |
| - | errors '' | + | |
| - | + | ||
| - | === 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. | + | |
| - | appears in '' | + | |
| - | match a predefined zone), and as a '' | + | |
| - | === Failures | + | 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 |
| + | WIP "How To" for Snapshot on the [[https:// | ||
| - | If domains which use DNSSEC fail to resolve while other domains work, check that the system time is correct. | + | Documentation: |
| + | * [[https:// | ||
| + | * [[https:// | ||
| + | * [[https:// | ||
| + | * [[https:// | ||
| - | === IPv6 === | + | Note there are significant options enhancements from 18.06 to 19.07 including UCI/LuCI for TLS. |
| - | 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. | ||