net/unbound/files/README.md

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