net/unbound/files/README.md

   1 # Unbound Recursive DNS Server with UCI
   2
   3 ## Unbound Description
   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.
   5
   6 ## Package Overview
   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.
   8
   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.
  10
  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.
  12
  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.
  15
  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:
  17
  18 **/etc/config/firewall**:
  19 ```
  20 config rule
  21   option name 'Block-Public-DNS'
  22   option enabled '1'
  23   option src 'lan'
  24   option dest 'wan'
  25   option dest_port '53 853 5353'
  26   option proto 'tcpudp'
  27   option family 'any'
  28   option target 'REJECT'
  29 ```
  30
  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.
  33
  34 ### Serial dnsmasq
  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.
  36
  37 **/etc/config/unbound**:
  38 ```
  39 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'
  47   ...
  48 ```
  49
  50 **/etc/config/dhcp**:
  51 ```
  52 config dnsmasq
  53   option domain 'yourdomain'
  54   option noresolv '1'
  55   option resolvfile '/tmp/resolv.conf.auto'
  56   option port '53'
  57   list server '127.0.0.1#1053'
  58   list server '::1#1053'
  59   ...
  60 ```
  61
  62 ### Parallel dnsmasq
  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.
  64
  65 **/etc/config/unbound**:
  66 ```
  67 config unbound
  68   # likely you want to match domain option between Unbound and dnsmasq
  69   option domain 'yourdomain'
  70   option dhcp_link 'dnsmasq'
  71   option listen_port '53'
  72   ...
  73 ```
  74
  75 **/etc/config/dhcp**:
  76 ```
  77 config dnsmasq
  78   option domain 'yourdomain'
  79   option noresolv '1'
  80   option resolvfile '/tmp/resolv.conf.auto'
  81   option port '1053'
  82   ...
  83
  84 config dhcp 'lan'
  85   # dnsmasq may not issue DNS option if not std. configuration
  86   list dhcp_option 'option:dns-server,0.0.0.0'
  87   ...
  88 ```
  89
  90 ### Unbound and odhcpd
  91 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.
  92 - Default OpenWrt has dnsmasq+odhcpd with `odhcpd-ipv6only` limited to DHCPv6.
  93 - If you use dnsmasq+odhcpd together, then use dnsmasq serial or parallel methods above.
  94 - You must install package `odhcpd` (full) to use odhcpd alone.
  95 - You must install package `unbound-control` to load and unload leases.
  96 - Remember to uninstall (or disable) dnsmasq when you won't use it.
  97
  98 **/etc/config/unbound**:
  99 ```
 100 config unbound
 101   # name your router in DNS
 102   option add_local_fqdn '1'
 103   option add_wan_fqdn '1'
 104   option dhcp_link 'odhcpd'
 105   # add SLAAC inferred from DHCPv4
 106   option dhcp4_slaac6 '1'
 107   option domain 'lan'
 108   option domain_type 'static'
 109   option listen_port '53'
 110   option rebind_protection '1'
 111   # install unbound-control and set this
 112   option unbound_control '1'
 113   ...
 114 ```
 115
 116 **/etc/config/dhcp**:
 117 ```
 118 config dhcp 'lan'
 119   option dhcpv4 'server'
 120   option dhcpv6 'server'
 121   option interface 'lan'
 122   option leasetime '12h'
 123   option ra 'server'
 124   option ra_management '1'
 125   ...
 126
 127 config odhcpd 'odhcpd'
 128   option maindhcp '1'
 129   option leasefile '/var/lib/odhcpd/dhcp.leases'
 130   # this is where the magic happens
 131   option leasetrigger '/usr/lib/unbound/odhcpd.sh'
 132 ```
 133
 134 ## HOW TO: Manual Override
 135 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.
 136
 137 ### Completely Manual (almost)
 138 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`.
 139
 140 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).
 141
 142 **/etc/config/unbound**:
 143 ```
 144 config unbound
 145   option manual_conf '1'
 146   option root_age '9'
 147   # end
 148 ```
 149
 150 ### Hybrid Manual/UCI
 151 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.
 152
 153 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.
 154
 155 ## HOW TO: Cache Zone Files
 156 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.
 157
 158 **/etc/config/unbound**:
 159 ```
 160 config zone
 161   option enabled '1'
 162   option fallback '1'
 163   option url_dir 'https://asset-management.it.example.com/zones/'
 164   option zone_type 'auth_zone'
 165   list server 'ns1.it.example.com'
 166   list server 'ns2.it.example.com'
 167   list zone_name 'example.com'
 168 ```
 169
 170 ## HOW TO: TLS Over DNS
 171 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.
 172
 173 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.
 174
 175 **/etc/config/unbound**:
 176 ```
 177 config zone
 178   option enabled '1'
 179   # question: do you want to recurse when TLS fails or not?
 180   option fallback '0'
 181   option tls_index 'dns.example.net'
 182   option tls_port '853'
 183   option tls_upstream '1'
 184   option zone_type 'forward_zone'
 185   # these servers assume a common TLS port/index
 186   list server '192.0.2.53'
 187   list server '2001:db8::53'
 188   # this alternate server is fully specified inline
 189   list server '192.0.2.153@443#dns.alternate.example.org'
 190   list zone_name '.'
 191 ```
 192
 193 ## Optional Compile Switches
 194 Unbound can be changed by toggling switches within `make menuconfig` Libraries/Network/libunbound. Disable libevent, libpthread, and ipset to attempt to gain performance and size on small single core targets. These downgrade options are well tested, but they are not needed unless Unbound will not fit. Take care before enabling subnetcache, dnscrypt, and python options. These enhancements are not fully tested within OpenWrt and python is a large dependency. These enhancements are default off and they do not have UCI. You will need to use the files `/etc/unbound/unbound_srv.conf` and `/etc/unbound/unbound_ext.conf` to configure these modules. The `server:` clause line `module: subnetcache validator python iterator` will be filled out if the modules are compiled in.
 195
 196 Note: if you use python, then you will need to manual configure and you cannot use chroot. The scripts are not yet enhanced enough to set up the directory binding.
 197
 198 ## Complete List of UCI Options
 199 **/etc/config/unbound**:
 200 ```
 201 config unbound
 202   Currently only one instance is supported.
 203
 204   option add_extra_dns '0'
 205     Level. Execute traditional DNS overrides found in `/etc/config/dhcp`.
 206     Optional so you may use other Unbound conf or redirect to NSD instance.
 207     0 - Ignore `/etc/config/dhcp`
 208     1 - Use only 'domain' clause (host records)
 209     2 - Use 'domain', 'mxhost', and 'srvhost' clauses
 210     3 - Use all of 'domain', 'mxhost', 'srvhost', and 'cname' clauses
 211
 212   option add_local_fqdn '0'
 213     Level. This puts your routers host name in the LAN (local) DNS.
 214     Each level is more detailed and comprehensive.
 215     0 - Disabled
 216     1 - Host Name on only the primary address
 217     2 - Host Name on all addresses found (except link)
 218     3 - FQDN and host name on all addresses (except link)
 219     4 - Above and interfaces named <iface>.<hostname>.<domain>
 220
 221   option add_wan_fqdn '0'
 222     Level. Same as previous option only this applies to the WAN. WAN are
 223     inferred by a UCI `config dhcp` entry that contains the 'option ignore 1'.
 224
 225   option dns_assist 'none'
 226     Program Name. Use DNS helpers found on local host and match to their UCI.
 227     Only program 'ipset-dns' is supported so far. NSD and Bind might be useful
 228     but they don't have UCI to parse.
 229
 230   option dns64 '0'
 231     Boolean. Enable DNS64 through Unbound in order to bridge networks that are
 232     IPV6 only and IPV4 only (see RFC6052).
 233
 234   option dns64_prefix '64:ff9b::/96'
 235     IPV6 Prefix. The IPV6 prefix wrapped on the IPV4 address for DNS64. You
 236     should use RFC6052 "well known" address, unless you also redirect to a proxy
 237     or gateway for your NAT64.
 238
 239   option dhcp_link 'none'
 240     Program Name. Link to one of the supported programs we have scripts
 241     for. You may also need to install a trigger script in the DHCP
 242     servers configuration. See HOW TO above.
 243
 244   option dhcp4_slaac6 '0'
 245     Boolean. Some DHCP servers do this natively (dnsmasq). Otherwise
 246     the script provided with this package will try to fabricate SLAAC
 247     IP6 addresses from DHCPv4 MAC records.
 248
 249   option domain 'lan'
 250     Unbound local-zone: <domain> <type>. This is used to suffix all
 251     host records, and maintain a local zone. When dnsmasq is dhcp_link
 252     however, then this option is ignored (dnsmasq does it all).
 253
 254   option domain_type 'static'
 255     Unbound local-zone: <domain> <type>. This allows you to lock
 256     down or allow forwarding of the local zone. Notable types:
 257     static - typical single router setup much like OpenWrt dnsmasq default
 258     refuse - to answer overtly with DNS code REFUSED
 259     deny - to drop queries for the local zone
 260     transparent - to use your manually added forward-zone: or stub-zone: clause
 261
 262   option edns_size '1280'
 263     Bytes. Extended DNS is necessary for DNSSEC. However, it can run
 264     into MTU issues. Use this size in bytes to manage drop outs.
 265
 266   option extended_stats '0'
 267     Boolean. extended statistics are printed from unbound-control.
 268     Keeping track of more statistics takes time.
 269
 270   option hide_binddata '1'
 271     Boolean. If enabled version.server, version.bind, id.server, and
 272     hostname.bind queries are refused.
 273
 274   option interface_auto '1'
 275     Boolean. If enabled DNS replies will have the same source address as
 276     the request was sent to.
 277
 278   option listen_port '53'
 279     Port. Incoming. Where Unbound will listen for queries.
 280
 281   option localservice '1'
 282     Boolean. Prevent DNS amplification attacks. Only provide access to
 283     Unbound from subnets this machine has interfaces on.
 284
 285   option manual_conf '0'
 286     Boolean. Skip all this UCI nonsense. Manually edit the
 287     configuration. Make changes to /etc/unbound/unbound.conf.
 288
 289   option num_threads '1'
 290     Count. Enable multithreading with the "heavy traffic" variant. Base variant
 291     spins each as whole proces and is not efficient. Two threads may be used,
 292     but they use one shared cache slab. More edges into an industrial setup,
 293     and UCI simplificaitons may not be appropriate.
 294
 295   option protocol 'mixed'
 296     Unbound can limit its protocol used for recursive queries.
 297     ip4_only - old fashioned IPv4 upstream and downstream
 298     ip6_only - test environment only; could cauase problems
 299     ip6_local - upstream IPv4 only and local network IPv4 and IPv6
 300     ip6_prefer - both IPv4 and IPv6 but try IPv6 first
 301     mixed - both IPv4 and IPv6
 302     default - Unbound built-in defaults
 303
 304   option query_minimize '0'
 305     Boolean. Enable a minor privacy option. Don't let each server know the next
 306     recursion. Query one piece at a time.
 307
 308   option query_min_strict '0'
 309     Boolean. Query minimize is best effort and will fall back to normal when it
 310     must. This option prevents the fall back, but less than standard name
 311     servers will fail to resolve their domains.
 312
 313   option rebind_localhost '0'
 314     Boolean. Prevent loopback "127.0.0.0/8" or "::1/128" responses. These may
 315     used by black hole servers for good purposes like ad-blocking or parental
 316     access control. Obviously these responses may be used to for bad purposes.
 317
 318   option rebind_protection '1'
 319     Level. Block your local address responses from global DNS. A poisoned
 320     reponse within "192.168.0.0/24" or "fd00::/8" could turn a local browser
 321     into an external attack proxy server. IP6 GLA may be vulnerable also.
 322     0 - Off
 323     1 - Only RFC 1918 and 4193 responses blocked
 324     2 - Plus GLA /64 on designated interface(s)
 325     3 - Plus DHCP-PD range passed down interfaces (not implemented)
 326
 327   option recursion 'passive'
 328     Unbound has many options for recrusion but UCI is bundled for simplicity.
 329     passive - slower until cache fills but kind on CPU load
 330     default - Unbound built-in defaults
 331     aggressive - uses prefetching to handle more requests quickly
 332
 333   option resource 'small'
 334     Unbound has many options for resources but UCI is bundled for simplicity.
 335     tiny - similar to published memory restricted configuration
 336     small - about half of medium
 337     medium - similar to default, but fixed for consistency
 338     default - Unbound built-in defaults
 339     large - about double of medium
 340
 341   option root_age '9'
 342     Days. >90 Disables. Age limit for Unbound root data like root DNSSEC key.
 343     Unbound uses RFC 5011 to manage root key. This could harm flash ROM. This
 344     activity is mapped to "tmpfs," but every so often it needs to be copied back
 345     to flash for the next reboot.
 346
 347   option ttl_min '120'
 348     Seconds. Minimum TTL in cache. Recursion can be expensive without cache. A
 349     low TTL is normal for server migration. A low TTL can be abused for snoop-
 350     vertising (DNS hit counts; recording query IP). Typical to configure maybe
 351     0~300, but 1800 is the maximum accepted.
 352
 353   option unbound_control '0'
 354     Level. Enables unbound-control application access ports.
 355     0 - No unbound-control Access, or add your own in 'unbound_ext.conf'
 356     1 - Unencrypted Local Host Access
 357     2 - SSL Local Host Access; auto unbound-control-setup if available
 358     3 - SSL Network Access; auto unbound-control-setup if available
 359     4 - SSL Network Access; static key/pem files must already exist
 360
 361   option validator '0'
 362     Boolean. Enable DNSSEC. Unbound names this the "validator" module.
 363
 364   option validator_ntp '1'
 365     Boolean. Disable DNSSEC time checks at boot. Once NTP confirms global real
 366     time, then DNSSEC is restarted at full strength. Many embedded devices don't
 367     have a real time power off clock. NTP needs DNS to resolve servers. This
 368     works around the chicken-and-egg.
 369
 370   option verbosity '1'
 371     Level. Sets Unbounds logging intensity.
 372
 373   list domain_insecure 'ntp.somewhere.org'
 374     Domain. Domains that you wish to skip DNSSEC. It is one way around NTP
 375     chicken and egg. Your DHCP servered domains are automatically included.
 376
 377   list trigger_interface 'lan' 'wan'
 378     Interface (logical). This option is a work around for netifd/procd
 379     interaction with WAN DHCPv6. Minor RA or DHCP changes in IP6 can cause
 380     netifd to execute procd interface reload. Limit Unbound procd triggers to
 381     LAN and WAN (IP4 only) to prevent restart @2-3 minutes.
 382
 383
 384 config zone
 385   Create Unbounds forward-zone:, stub-zone:, or auth-zone: clauses
 386
 387   option enabled 1
 388     Boolean. Enable the zone clause.
 389
 390   option fallback 1
 391     Boolean. Permit normal recursion when the narrowly selected servers in this
 392     zone are unresponsive or return empty responses. Disable, if there are
 393     security concerns (forward only internal to organization).
 394
 395   option port 53
 396     Port. Servers are contact on this port for plain DNS operations.
 397
 398   option resolv_conf 0
 399     Boolean. Use "resolv.conf" as it was filled by the DHCP client. This can be
 400     used to forward zones within your ISP (mail.example.net) or that have co-
 401     located services (streamed-movies.example.com). Recursion may not yield the
 402     most local result, but forwarding may instead.
 403
 404   option tls_index (n/a)
 405     Domain. Name TLS certificates are signed for (dns.example.net). If this
 406     option is ommitted, then Unbound will make connections but not validate.
 407
 408   option tls_port 853
 409     Port. Servers are contact on this port for DNS over TLS operations.
 410
 411   option tls_upstream 0
 412     Boolean. Use TLS to contact the zone server.
 413
 414   option url_dir
 415     String. http or https path, directory part only, to the zone file for
 416     auth_zone type only. Files "${zone_name}.zone" are expect in this path.
 417
 418   option zone_type (n/a)
 419     State. Required field or the clause is effectively disabled. Check Unbound
 420     documentation for clarity (unbound-conf).
 421     auth_zone     - prefetch whole zones from authoritative server (ICANN)
 422     forward_zone  - forward queries in these domains to the listed servers
 423     stub_zone     - force recursion of these domains to the listed servers
 424
 425   list server (n/a)
 426     IP. Every zone must have one server. Stub and forward require IP to prevent
 427     chicken and egg (due to UCI simplicity). Authoritative prefetch may use a
 428     server name.
 429
 430   list zone_name
 431     Domain. Every zone must represent some part of the DNS tree. It can be all
 432     of it "." or you internal organization domain "example.com." Within each
 433     zone clause all zone names will be matched to all servers.
 434 ```
 435
 436 ## Replaced Options
 437   config unbound / option prefetch_root
 438     List the domains in a zone with type auth_zone and fill in the server or url
 439     fields. Root zones are ready but disabled in default install UCI.
 440
 441   config unbound / list domain_forward
 442     List the domains in a zone with type forward_zone and enable the
 443     resolv_conf option.
 444
 445   config unbound / list rebind_interface
 446     Enable rebind_protection at 2 and all DHCP interfaces are also protected for
 447     IPV6 GLA (parallel to subnets in add_local_fqdn).
 448