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