You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

303 lines
14 KiB

  1. # Unbound Recursive DNS Server with UCI
  2. ## Unbound Description
  3. [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.
  4. ## Package Overview
  5. Unbound may be useful on consumer grade embedded hardware. 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.
  6. 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 work at the raw "unbound.conf" level.
  7. ## HOW TO Adblocking
  8. The UCI scripts will work with [net/adblock 2.3+](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.
  9. ## HOW TO Integrate with DHCP
  10. 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.
  11. ### Serial dnsmasq
  12. In this case, dnsmasq is not changed *much* with respect to the default OpenWRT/LEDE 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. dnsmasq and Unbound effectively have the same information in memory, and all transfers are double handled.
  13. **/etc/config/unbound**:
  14. ```
  15. config unbound
  16. option add_local_fqdn '0'
  17. option add_wan_fqdn '0'
  18. option dhcp_link 'none'
  19. # dnsmasq should not forward your domain to unbound, but if...
  20. option domain 'yourdomain'
  21. option domain_type 'refuse'
  22. option listen_port '1053'
  23. ...
  24. ```
  25. **/etc/config/dhcp**:
  26. ```
  27. config dnsmasq
  28. option domain 'yourdomain'
  29. option noresolv '1'
  30. option resolvfile '/tmp/resolv.conf.auto'
  31. option port '53'
  32. list server '127.0.0.1#1053'
  33. list server '::1#1053'
  34. ...
  35. ```
  36. ### Parallel dnsmasq
  37. 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.
  38. **/etc/config/unbound**:
  39. ```
  40. config unbound
  41. option dhcp_link 'dnsmasq'
  42. option listen_port '53'
  43. ...
  44. ```
  45. **/etc/config/dhcp**:
  46. ```
  47. config dnsmasq
  48. option domain 'yourdomain'
  49. option noresolv '1'
  50. option resolvfile '/tmp/resolv.conf.auto'
  51. option port '1053'
  52. ...
  53. config dhcp 'lan'
  54. # dnsmasq may not issue DNS option if not std. configuration
  55. list dhcp_option 'option:dns-server,0.0.0.0'
  56. ...
  57. ```
  58. ### Unbound and odhcpd
  59. You may ask, "can Unbound replace dnsmasq?" You can have DHCP-DNS records with Unbound and odhcpd 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. You **must install** `unbound-control`, because the lease records are added and removed without starting, stopping, flushing cache, or re-writing conf files. (_restart overhead can be excessive with even a few mobile devices._)
  60. Don't forget to disable or uninstall dnsmasq when you don't intend to use it. Strange results may occur. If you want to use default dnsmasq+odhcpd and add Unbound on top, then use the dnsmasq-serial or dnsmasq-parallel methods above.
  61. **/etc/config/unbound**:
  62. ```
  63. config unbound
  64. # name your router in DNS
  65. option add_local_fqdn '1'
  66. option add_wan_fqdn '1'
  67. option dhcp_link 'odhcpd'
  68. # add SLAAC inferred from DHCPv4
  69. option dhcp4_slaac6 '1'
  70. option domain 'lan'
  71. option domain_type 'static'
  72. option listen_port '53'
  73. option rebind_protection '1'
  74. # install unbound-control and set this
  75. option unbound_control '1'
  76. ...
  77. ```
  78. **/etc/config/dhcp**:
  79. ```
  80. config dhcp 'lan'
  81. option dhcpv4 'server'
  82. option dhcpv6 'server'
  83. option interface 'lan'
  84. option leasetime '12h'
  85. option ra 'server'
  86. option ra_management '1'
  87. # odhcpd should issue ULA [fd00::/8] by default
  88. ...
  89. config odhcpd 'odhcpd'
  90. option maindhcp '1'
  91. option leasefile '/var/lib/odhcpd/dhcp.leases'
  92. # this is where the magic happens
  93. option leasetrigger '/usr/lib/unbound/odhcpd.sh'
  94. ```
  95. ## HOW TO Manual Override
  96. 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.
  97. ### Completely Manual (almost)
  98. 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`.
  99. 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).
  100. **/etc/config/unbound**:
  101. ```
  102. config unbound
  103. option manual_conf '1'
  104. option root_age '9'
  105. # end
  106. ```
  107. ### Hybrid Manual/UCI
  108. 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.
  109. The former will be added to the end of the `server:` clause. The later will be added to the end of the file for extended `forward:` 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.
  110. ## Complete List of UCI Options
  111. **/etc/config/unbound**:
  112. ```
  113. config unbound
  114. Currently only one instance is supported.
  115. option add_extra_dns '0'
  116. Level. Execute traditional DNS overrides found in `/etc/config/dhcp`.
  117. Optional so you may use other Unbound conf or redirect to NSD instance.
  118. 0 - Ignore `/etc/config/dhcp`
  119. 1 - Use only 'domain' clause (host records)
  120. 2 - Use 'domain', 'mxhost', and 'srvhost' clauses
  121. 3 - Use all of 'domain', 'mxhost', 'srvhost', and 'cname' clauses
  122. option add_local_fqdn '0'
  123. Level. This puts your routers host name in the LAN (local) DNS.
  124. Each level is more detailed and comprehensive.
  125. 0 - Disabled
  126. 1 - Host Name on only the primary address
  127. 2 - Host Name on all addresses found (except link)
  128. 3 - FQDN and host name on all addresses (except link)
  129. 4 - Above and interfaces named <iface>.<hostname>.<domain>
  130. option add_wan_fqdn '0'
  131. Level. Same as previous option only this applies to the WAN. WAN
  132. are inferred by a UCI `config dhcp` entry that contains the line
  133. option ignore '1'.
  134. option dns64 '0'
  135. Boolean. Enable DNS64 through Unbound in order to bridge networks
  136. that are IPV6 only and IPV4 only (see RFC6052).
  137. option dns64_prefix '64:ff9b::/96'
  138. IPV6 Prefix. The IPV6 prefix wrapped on the IPV4 address for DNS64.
  139. You should use RFC6052 "well known" address, unless you also
  140. redirect to a proxy or gateway for your NAT64.
  141. option dhcp_link 'none'
  142. Program Name. Link to one of the supported programs we have scripts
  143. for. You may also need to install a trigger script in the DHCP
  144. servers configuration. See HOW TO above.
  145. option dhcp4_slaac6 '0'
  146. Boolean. Some DHCP servers do this natively (dnsmasq). Otherwise
  147. the script provided with this package will try to fabricate SLAAC
  148. IP6 addresses from DHCPv4 MAC records.
  149. option domain 'lan'
  150. Unbound local-zone: <domain> <type>. This is used to suffix all
  151. host records, and maintain a local zone. When dnsmasq is dhcp_link
  152. however, then this option is ignored (dnsmasq does it all).
  153. option domain_type 'static'
  154. Unbound local-zone: <domain> <type>. This allows you to lock
  155. down or allow forwarding of your domain, your router host name
  156. without suffix, and leakage of RFC6762 "local."
  157. option edns_size '1280'
  158. Bytes. Extended DNS is necessary for DNSSEC. However, it can run
  159. into MTU issues. Use this size in bytes to manage drop outs.
  160. option extended_luci '0'
  161. Boolean. Extends a tab hierarchy in LuCI for advanced congfiguration.
  162. option extended_stats '0'
  163. Boolean. extended statistics are printed from unbound-control.
  164. Keeping track of more statistics takes time.
  165. option hide_binddata '1'
  166. Boolean. If enabled version.server, version.bind, id.server, and
  167. hostname.bind queries are refused.
  168. option listen_port '53'
  169. Port. Incoming. Where Unbound will listen for queries.
  170. option localservice '1'
  171. Boolean. Prevent DNS amplification attacks. Only provide access to
  172. Unbound from subnets this machine has interfaces on.
  173. option manual_conf '0'
  174. Boolean. Skip all this UCI nonsense. Manually edit the
  175. configuration. Make changes to /etc/unbound/unbound.conf.
  176. option protocol 'mixed'
  177. Unbound can limit its protocol used for recursive queries.
  178. Set 'ip4_only' to avoid issues if you do not have native IP6.
  179. Set 'ip6_prefer' to possibly improve performance as well as
  180. not consume NAT paths for the client computers.
  181. Do not use 'ip6_only' unless testing.
  182. option query_minimize '0'
  183. Boolean. Enable a minor privacy option. Don't let each server know
  184. the next recursion. Query one piece at a time.
  185. option query_min_strict '0'
  186. Boolean. Query minimize is best effort and will fall back to normal
  187. when it must. This option prevents the fall back, but less than
  188. standard name servers will fail to resolve their domains.
  189. option rebind_localhost '0'
  190. Boolean. Prevent loopback "127.0.0.0/8" or "::1/128" responses.
  191. These may used by black hole servers for good purposes like
  192. ad-blocking or parental access control. Obviously these responses
  193. also can be used to for bad purposes.
  194. option rebind_protection '1'
  195. Boolean. Prevent RFC 1918 Reponses from global DNS. Example a
  196. poisoned reponse within "192.168.0.0/24" could be used to turn a
  197. local browser into an external attack proxy server.
  198. option recursion 'passive'
  199. Unbound has numerous options for how it recurses. This UCI combines
  200. them into "passive," "aggressive," or Unbound's own "default."
  201. Passive is easy on resources, but slower until cache fills.
  202. option resource 'small'
  203. Unbound has numerous options for resources. This UCI gives "tiny,"
  204. "small," "medium," and "large." Medium is most like the compiled
  205. defaults with a bit of balancing. Tiny is close to the published
  206. memory restricted configuration. Small 1/2 medium, and large 2x.
  207. option root_age '9'
  208. Days. >90 Disables. Age limit for Unbound root data like root
  209. DNSSEC key. Unbound uses RFC 5011 to manage root key. This could
  210. harm flash ROM. This activity is mapped to "tmpfs," but every so
  211. often it needs to be copied back to flash for the next reboot.
  212. option ttl_min '120'
  213. Seconds. Minimum TTL in cache. Recursion can be expensive without
  214. cache. A low TTL is normal for server migration. A low TTL can be
  215. abused for snoop-vertising (DNS hit counts; recording query IP).
  216. Typical to configure maybe 0~300, but 1800 is the maximum accepted.
  217. option unbound_control '0'
  218. Level. Enables unbound-control application access ports.
  219. 0 - No unbound-control Access, or add your own in 'unbound_ext.conf'
  220. 1 - Unencrypted Local Host Access
  221. 2 - SSL Local Host Access; auto unbound-control-setup if available
  222. 3 - SSL Network Access; auto unbound-control-setup if available
  223. 4 - SSL Network Access; static key/pem files must already exist
  224. option validator '0'
  225. Boolean. Enable DNSSEC. Unbound names this the "validator" module.
  226. option validator_ntp '1'
  227. Boolean. Disable DNSSEC time checks at boot. Once NTP confirms
  228. global real time, then DNSSEC is restarted at full strength. Many
  229. embedded devices don't have a real time power off clock. NTP needs
  230. DNS to resolve servers. This works around the chicken-and-egg.
  231. list domain_insecure 'www.example.com'
  232. Domain. Domains that you wish to skip DNSSEC. Your DHCP
  233. domains and pointers will get this automatically.
  234. list trigger 'lan' 'wan'
  235. Interface (logical). This option is a work around for netifd/procd
  236. interaction with WAN DHCPv6. Minor RA or DHCP changes in IP6 can
  237. cause netifd to execute procd interface reload. Limit Unbound procd
  238. triggers to LAN and WAN (IP4 only) to prevent restart @2-3 minutes.
  239. ```