1 # Unbound Recursive DNS Server with UCI
4 [Unbound](https://www.unbound.net/) is a validating, recursive, and caching DNS resolver. The C implementation of Unbound is developed and maintained by [NLnet Labs](https://www.nlnetlabs.nl/). It is based on ideas and algorithms taken from a java prototype developed by Verisign labs, Nominet, Kirei and ep.net. Unbound is designed as a set of modular components, so that also DNSSEC (secure DNS) validation and stub-resolvers (that do not run as a server, but are linked into an application) are easily possible.
7 OpenWrt default build uses [dnsmasq](http://www.thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html) for DNS forwarding and DHCP. With a forward only resolver, dependence on the upstream recursors may be cause for concern. They are often provided by the ISP, and some users have switched to public DNS providers. Either way may result in problems due to performance, "snoop-vertising", hijacking (MiM), and other causes. Running a recursive resolver or resolver capable of TLS may be a solution.
9 Unbound may be useful on consumer grade embedded hardware. It is fully DNSSEC and TLS capable. It is _intended_ to be a recursive resolver only. NLnet Labs [NSD](https://www.nlnetlabs.nl/projects/nsd/) is _intended_ for the authoritative task. This is different than [ISC Bind](https://www.isc.org/downloads/bind/) and its inclusive functions. Unbound configuration effort and memory consumption may be easier to control. A consumer could have their own recursive resolver with 8/64 MB router, and remove potential issues from forwarding resolvers outside of their control.
11 This package builds on Unbounds capabilities with OpenWrt UCI. Not every Unbound option is in UCI, but rather, UCI simplifies the combination of related options. Unbounds native options are bundled and balanced within a smaller set of choices. Options include resources, DNSSEC, access control, and some TTL tweaking. The UCI also provides an escape option and works at the raw "unbound.conf" level.
13 ## HOW TO: Ad Blocking
14 The UCI scripts will work with [net/adblock](https://github.com/openwrt/packages/blob/master/net/adblock/files/README.md), if it is installed and enabled. Its all detected and integrated automatically. In brief, the adblock scripts create distinct local-zone files that are simply included in the unbound conf file during UCI generation. If you don't want this, then disable adblock or reconfigure adblock to not send these files to Unbound.
16 A few tweaks may be needed to enhance the realiability and effectiveness. Ad Block option for delay time may need to be set for upto one minute (adb_triggerdelay), because of boot up race conditions with interfaces calling Unbound restarts. Also many smart devices (TV, microwave, or refigerator) will also use public DNS servers either as a bypass or for certain connections in general. If you wish to force exclusive DNS to your router, then you will need a firewall rule for example:
18 **/etc/config/firewall**:
21 option name 'Block-Public-DNS'
25 option dest_port '53 853 5353'
28 option target 'REJECT'
31 ## HOW TO: Integrate with DHCP
32 Some UCI options and scripts help Unbound to work with DHCP servers to load the local DNS. The examples provided here are serial dnsmasq-unbound, parallel dnsmasq-unbound, and unbound scripted with odhcpd.
35 In this case, dnsmasq is not changed *much* with respect to the default [OpenWrt](https://openwrt.org/docs/guide-user/base-system/dns_configuration) configuration. Here dnsmasq is forced to use the local Unbound instance as the lone upstream DNS server, instead of your ISP. This may be the easiest implementation, but performance degradation can occur in high volume networks. Unbound and dnsmasq effectively have the same information in memory, and all transfers are double handled.
37 **/etc/config/unbound**:
40 option add_local_fqdn '0'
41 option add_wan_fqdn '0'
42 option dhcp_link 'none'
43 # dnsmasq should not forward your domain to unbound, but if...
44 option domain 'yourdomain'
45 option domain_type 'refuse'
46 option listen_port '1053'
53 option domain 'yourdomain'
55 option resolvfile '/tmp/resolv.conf.auto'
57 list server '127.0.0.1#1053'
58 list server '::1#1053'
63 In this case, Unbound serves your local network directly for all purposes. It will look over to dnsmasq for DHCP-DNS resolution. Unbound is generally accessible on port 53, and dnsmasq is only accessed at 127.0.0.1:1053 by Unbound. Although you can dig/drill/nslookup remotely with the proper directives.
65 **/etc/config/unbound**:
68 option dhcp_link 'dnsmasq'
69 option listen_port '53'
76 option domain 'yourdomain'
78 option resolvfile '/tmp/resolv.conf.auto'
83 # dnsmasq may not issue DNS option if not std. configuration
84 list dhcp_option 'option:dns-server,0.0.0.0'
88 ### Unbound and odhcpd
89 You may ask, "can Unbound replace dnsmasq?" You can have DHCP-DNS records with Unbound and [odhcpd](https://github.com/openwrt/odhcpd/blob/master/README) only. The UCI scripts will allow Unbound to act like dnsmasq. When odhcpd configures each DHCP lease, it will call a script. The script provided with Unbound will read the lease file for DHCP-DNS records. The unbound-control application is required, because simply rewriting conf-files and restarting unbound is too much overhead.
90 - Default OpenWrt has dnsmasq+odhcpd with `odhcpd-ipv6only` limited to DHCPv6.
91 - If you use dnsmasq+odhcpd together, then use dnsmasq serial or parallel methods above.
92 - You must install package `odhcpd` (full) to use odhcpd alone.
93 - You must install package `unbound-control` to load and unload leases.
94 - Remember to uninstall (or disable) dnsmasq when you won't use it.
96 **/etc/config/unbound**:
99 # name your router in DNS
100 option add_local_fqdn '1'
101 option add_wan_fqdn '1'
102 option dhcp_link 'odhcpd'
103 # add SLAAC inferred from DHCPv4
104 option dhcp4_slaac6 '1'
106 option domain_type 'static'
107 option listen_port '53'
108 option rebind_protection '1'
109 # install unbound-control and set this
110 option unbound_control '1'
114 **/etc/config/dhcp**:
117 option dhcpv4 'server'
118 option dhcpv6 'server'
119 option interface 'lan'
120 option leasetime '12h'
122 option ra_management '1'
125 config odhcpd 'odhcpd'
127 option leasefile '/var/lib/odhcpd/dhcp.leases'
128 # this is where the magic happens
129 option leasetrigger '/usr/lib/unbound/odhcpd.sh'
132 ## HOW TO: Manual Override
133 Yes, there is a UCI to disable the rest of Unbound UCI. However, OpenWrt or LEDE are targeted at embedded machines with flash ROM. The initialization scripts do a few things to protect flash ROM.
135 ### Completely Manual (almost)
136 All of `/etc/unbound` (persistent, ROM) is copied to `/var/lib/unbound` (tmpfs, RAM). Edit your manual `/etc/unbound/unbound.conf` to reference this `/var/lib/unbound` location for included files. Note in preparation for a jail, `/var/lib/unbound` is `chown unbound`. Configure for security in`/etc/unbound/unbound.conf` with options `username:unbound` and `chroot:/var/lib/unbound`.
138 Keep the DNSKEY updated with your choice of flash activity. `root.key` maintenance for DNSKEY RFC5011 would be hard on flash. Unbound natively updates frequently. It also creates and destroys working files in the process. In `/var/lib/unbound` this is no problem, but it would be gone at the next reboot. If you have DNSSEC (validator) active, then you should consider the age UCI option. Choose how many days to copy from `/var/lib/unbound/root.key` (tmpfs) to `/etc/unbound/root.key` (flash).
140 **/etc/config/unbound**:
143 option manual_conf '1'
148 ### Hybrid Manual/UCI
149 You like the UCI. Yet, you need to add some difficult to standardize options, or just are not ready to make a UCI request yet. The files `/etc/unbound/unbound_srv.conf` and `/etc/unbound/unbound_ext.conf` will be copied to Unbounds chroot directory and included during auto generation.
151 The file `unbound_srv.conf` will be added into the `server:` clause. The file `unbound_ext.conf` will be added to the end of all configuration. It is for extended `forward-zone:`, `stub-zone:`, `auth-zone:`, and `view:` clauses. You can also disable unbound-control in the UCI which only allows "localhost" connections unencrypted, and then add an encrypted remote `control:` clause.
153 ## HOW TO: Cache Zone Files
154 Unbound has the ability to AXFR a whole zone from an authoritative server to prefetch the zone. This can speed up access to common zones. Some may have special bandwidth concerns for DNSSEC overhead. The following is a generic example. UCI defaults include the [root](https://www.internic.net/domain/) zone, but it is disabled as a ready to go example.
156 **/etc/config/unbound**:
161 option url_dir 'https://asset-management.it.example.com/zones/'
162 option zone_type 'auth_zone'
163 list server 'ns1.it.example.com'
164 list server 'ns2.it.example.com'
165 list zone_name 'example.com'
168 ## HOW TO: TLS Over DNS
169 Unbound can use TLS as a client or server. UCI supports Unbound as a forwarding client with TLS. Servers are more complex and need manual configuration. This may be desired for privacy against stealth tracking. Some public DNS servers seem to advertise help in this quest. If your looking for a better understanding, then some information can be found at [Cloudflare](https://www.cloudflare.com/) DNS [1.1.1.1](https://1.1.1.1/). The following is a generic example. You can mix providers by using complete server specificaiton to override the zones common port and certificate domain index.
171 Update as of Unbound 1.9.1, all TLS functions work correctly with either OpenSSL 1.0.2 or 1.1.0. Please be sure to install `ca-bundle` package and use `opkg` to get updates regularly.
173 **/etc/config/unbound**:
177 # question: do you want to recurse when TLS fails or not?
179 option tls_index 'dns.example.net'
180 option tls_port '853'
181 option tls_upstream '1'
182 option zone_type 'forward_zone'
183 # these servers assume a common TLS port/index
184 list server '192.0.2.53'
185 list server '2001:db8::53'
186 # this alternate server is fully specified inline
187 list server '192.0.2.153@443#dns.alternate.example.org'
191 ## Complete List of UCI Options
192 **/etc/config/unbound**:
195 Currently only one instance is supported.
197 option add_extra_dns '0'
198 Level. Execute traditional DNS overrides found in `/etc/config/dhcp`.
199 Optional so you may use other Unbound conf or redirect to NSD instance.
200 0 - Ignore `/etc/config/dhcp`
201 1 - Use only 'domain' clause (host records)
202 2 - Use 'domain', 'mxhost', and 'srvhost' clauses
203 3 - Use all of 'domain', 'mxhost', 'srvhost', and 'cname' clauses
205 option add_local_fqdn '0'
206 Level. This puts your routers host name in the LAN (local) DNS.
207 Each level is more detailed and comprehensive.
209 1 - Host Name on only the primary address
210 2 - Host Name on all addresses found (except link)
211 3 - FQDN and host name on all addresses (except link)
212 4 - Above and interfaces named <iface>.<hostname>.<domain>
214 option add_wan_fqdn '0'
215 Level. Same as previous option only this applies to the WAN. WAN are
216 inferred by a UCI `config dhcp` entry that contains the 'option ignore 1'.
219 Boolean. Enable DNS64 through Unbound in order to bridge networks that are
220 IPV6 only and IPV4 only (see RFC6052).
222 option dns64_prefix '64:ff9b::/96'
223 IPV6 Prefix. The IPV6 prefix wrapped on the IPV4 address for DNS64. You
224 should use RFC6052 "well known" address, unless you also redirect to a proxy
225 or gateway for your NAT64.
227 option dhcp_link 'none'
228 Program Name. Link to one of the supported programs we have scripts
229 for. You may also need to install a trigger script in the DHCP
230 servers configuration. See HOW TO above.
232 option dhcp4_slaac6 '0'
233 Boolean. Some DHCP servers do this natively (dnsmasq). Otherwise
234 the script provided with this package will try to fabricate SLAAC
235 IP6 addresses from DHCPv4 MAC records.
238 Unbound local-zone: <domain> <type>. This is used to suffix all
239 host records, and maintain a local zone. When dnsmasq is dhcp_link
240 however, then this option is ignored (dnsmasq does it all).
242 option domain_type 'static'
243 Unbound local-zone: <domain> <type>. This allows you to lock
244 down or allow forwarding of the local zone. Notable types:
245 static - typical single router setup much like OpenWrt dnsmasq default
246 refuse - to answer overtly with DNS code REFUSED
247 deny - to drop queries for the local zone
248 transparent - to use your manually added forward-zone: or stub-zone: clause
250 option edns_size '1280'
251 Bytes. Extended DNS is necessary for DNSSEC. However, it can run
252 into MTU issues. Use this size in bytes to manage drop outs.
254 option extended_stats '0'
255 Boolean. extended statistics are printed from unbound-control.
256 Keeping track of more statistics takes time.
258 option hide_binddata '1'
259 Boolean. If enabled version.server, version.bind, id.server, and
260 hostname.bind queries are refused.
262 option listen_port '53'
263 Port. Incoming. Where Unbound will listen for queries.
265 option localservice '1'
266 Boolean. Prevent DNS amplification attacks. Only provide access to
267 Unbound from subnets this machine has interfaces on.
269 option manual_conf '0'
270 Boolean. Skip all this UCI nonsense. Manually edit the
271 configuration. Make changes to /etc/unbound/unbound.conf.
273 option num_threads '1'
274 Count. Enable multithreading with the "heavy traffic" variant. Base variant
275 spins each as whole proces and is not efficient. Two threads may be used,
276 but they use one shared cache slab. More edges into an industrial setup,
277 and UCI simplificaitons may not be appropriate.
279 option protocol 'mixed'
280 Unbound can limit its protocol used for recursive queries.
281 ip4_only - old fashioned IPv4 upstream and downstream
282 ip6_only - test environment only; could cauase problems
283 ip6_local - upstream IPv4 only and local network IPv4 and IPv6
284 ip6_prefer - both IPv4 and IPv6 but try IPv6 first
285 mixed - both IPv4 and IPv6
286 default - Unbound built-in defaults
288 option query_minimize '0'
289 Boolean. Enable a minor privacy option. Don't let each server know the next
290 recursion. Query one piece at a time.
292 option query_min_strict '0'
293 Boolean. Query minimize is best effort and will fall back to normal when it
294 must. This option prevents the fall back, but less than standard name
295 servers will fail to resolve their domains.
297 option rebind_localhost '0'
298 Boolean. Prevent loopback "127.0.0.0/8" or "::1/128" responses. These may
299 used by black hole servers for good purposes like ad-blocking or parental
300 access control. Obviously these responses may be used to for bad purposes.
302 option rebind_protection '1'
303 Level. Block your local address responses from global DNS. A poisoned
304 reponse within "192.168.0.0/24" or "fd00::/8" could turn a local browser
305 into an external attack proxy server. IP6 GLA may be vulnerable also.
307 1 - Only RFC 1918 and 4193 responses blocked
308 2 - Plus GLA /64 on designated interface(s)
309 3 - Plus DHCP-PD range passed down interfaces (not implemented)
311 option recursion 'passive'
312 Unbound has many options for recrusion but UCI is bundled for simplicity.
313 passive - slower until cache fills but kind on CPU load
314 default - Unbound built-in defaults
315 aggressive - uses prefetching to handle more requests quickly
317 option resource 'small'
318 Unbound has many options for resources but UCI is bundled for simplicity.
319 tiny - similar to published memory restricted configuration
320 small - about half of medium
321 medium - similar to default, but fixed for consistency
322 default - Unbound built-in defaults
323 large - about double of medium
326 Days. >90 Disables. Age limit for Unbound root data like root DNSSEC key.
327 Unbound uses RFC 5011 to manage root key. This could harm flash ROM. This
328 activity is mapped to "tmpfs," but every so often it needs to be copied back
329 to flash for the next reboot.
332 Seconds. Minimum TTL in cache. Recursion can be expensive without cache. A
333 low TTL is normal for server migration. A low TTL can be abused for snoop-
334 vertising (DNS hit counts; recording query IP). Typical to configure maybe
335 0~300, but 1800 is the maximum accepted.
337 option unbound_control '0'
338 Level. Enables unbound-control application access ports.
339 0 - No unbound-control Access, or add your own in 'unbound_ext.conf'
340 1 - Unencrypted Local Host Access
341 2 - SSL Local Host Access; auto unbound-control-setup if available
342 3 - SSL Network Access; auto unbound-control-setup if available
343 4 - SSL Network Access; static key/pem files must already exist
346 Boolean. Enable DNSSEC. Unbound names this the "validator" module.
348 option validator_ntp '1'
349 Boolean. Disable DNSSEC time checks at boot. Once NTP confirms global real
350 time, then DNSSEC is restarted at full strength. Many embedded devices don't
351 have a real time power off clock. NTP needs DNS to resolve servers. This
352 works around the chicken-and-egg.
355 Level. Sets Unbounds logging intensity.
357 list domain_insecure 'ntp.somewhere.org'
358 Domain. Domains that you wish to skip DNSSEC. It is one way around NTP
359 chicken and egg. Your DHCP servered domains are automatically included.
361 list trigger_interface 'lan' 'wan'
362 Interface (logical). This option is a work around for netifd/procd
363 interaction with WAN DHCPv6. Minor RA or DHCP changes in IP6 can cause
364 netifd to execute procd interface reload. Limit Unbound procd triggers to
365 LAN and WAN (IP4 only) to prevent restart @2-3 minutes.
369 Create Unbounds forward-zone:, stub-zone:, or auth-zone: clauses
372 Boolean. Enable the zone clause.
375 Boolean. Permit normal recursion when the narrowly selected servers in this
376 zone are unresponsive or return empty responses. Disable, if there are
377 security concerns (forward only internal to organization).
380 Port. Servers are contact on this port for plain DNS operations.
383 Boolean. Use "resolv.conf" as it was filled by the DHCP client. This can be
384 used to forward zones within your ISP (mail.example.net) or that have co-
385 located services (streamed-movies.example.com). Recursion may not yield the
386 most local result, but forwarding may instead.
388 option tls_index (n/a)
389 Domain. Name TLS certificates are signed for (dns.example.net). If this
390 option is ommitted, then Unbound will make connections but not validate.
393 Port. Servers are contact on this port for DNS over TLS operations.
395 option tls_upstream 0
396 Boolean. Use TLS to contact the zone server.
399 String. http or https path, directory part only, to the zone file for
400 auth_zone type only. Files "${zone_name}.zone" are expect in this path.
402 option zone_type (n/a)
403 State. Required field or the clause is effectively disabled. Check Unbound
404 documentation for clarity (unbound-conf).
405 auth_zone - prefetch whole zones from authoritative server (ICANN)
406 forward_zone - forward queries in these domains to the listed servers
407 stub_zone - force recursion of these domains to the listed servers
410 IP. Every zone must have one server. Stub and forward require IP to prevent
411 chicken and egg (due to UCI simplicity). Authoritative prefetch may use a
415 Domain. Every zone must represent some part of the DNS tree. It can be all
416 of it "." or you internal organization domain "example.com." Within each
417 zone clause all zone names will be matched to all servers.
421 config unbound / option prefetch_root
422 List the domains in a zone with type auth_zone and fill in the server or url
423 fields. Root zones are ready but disabled in default install UCI.
425 config unbound / list domain_forward
426 List the domains in a zone with type forward_zone and enable the
429 config unbound / list rebind_interface
430 Enable rebind_protection at 2 and all DHCP interfaces are also protected for
431 IPV6 GLA (parallel to subnets in add_local_fqdn).