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 ## Work with dnsmasq
  12 Some UCI options will help Unbound and dnsmasq work together in **parallel**. The default DHCP and DNS stub resolver in OpenWrt is dnsmasq, and it will continue to serve this purpose. The following partial examples will make Unbound the primary DNS server, and make dnsmasq only provide DNS to local DHCP.
  13
  14 **/etc/config/unbound**:
  15
  16         config unbound
  17                 option dnsmasq_link_dns '1'
  18                 ...
  19
  20 **/etc/config/dhcp**:
  21
  22         config dnsmasq
  23                 option option noresolv '1'
  24                 option resolvfile '<empty>'
  25                 option port '1053'
  26                 ...
  27
  28         config dhcp '<name>'
  29                 list dhcp_option 'option:dns-server,0.0.0.0'
  30                 ...
  31
  32 Alternatives are mentioned here for completeness. DHCP event scripts which write host records are difficult to formulate for Unbound, NSD, or Bind. These programs sometimes need to be forcefully reloaded with host configuration, and reloads can bust cache. **Serial** configuration between dnsmasq and Unbound can be made on 127.0.0.1 with an off-port like #1053. This may double cache storage and incur unnecessary transfer delay.
  33
  34 ## Back to Manual Configuration
  35 You don't want UCI, but don't worry. We have UCI for that. However, OpenWrt or LEDE are targeted at embedded machines with flash ROM. The initialization scripts do a few things to protect flash ROM.
  36
  37 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`.
  38
  39 Finally, `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 this UCI option. Choose how many days to copy from `/var/lib/unbound/root.key` (tmpfs) to `/etc/unbound/root.key` (flash). Keep the DNSKEY updated with your choice of flash activity.
  40
  41 **/etc/config/unbound**:
  42
  43         config unbound
  44                 option manual_conf '1'
  45                 option root_age '30'
  46
  47 ## Complete List of UCI Options
  48 **/etc/config/unbound**:
  49
  50         config unbound
  51                 Currently only one instance is supported.
  52
  53         option dns64 '0'
  54                 Boolean. Enable DNS64 through Unbound in order to bridge networks
  55                 that are IPV6 only and IPV4 only (see RFC6052).
  56
  57         option dns64_prefix '64:ff9b::/96'
  58                 IPV6 Prefix. The IPV6 prefix wrapped on the IPV4 address for DNS64.
  59                 You should use RFC6052 "well known" address, unless you also
  60                 redirect to a proxy or gateway for your NAT64.
  61
  62         option dnsmasq_gate_name '0'
  63                 Boolean. Forward PTR records for interfaces not serving DHCP.
  64                 Assume these are WAN. Example dnsmasq option here to provide
  65                 logs with a name when your ISP won't link DHCP-DNS.
  66                 "dnsmasq.conf: interface-name=way-out.myrouter.lan,eth0.1"
  67
  68         option dnsmasq_link_dns '0'
  69                 Boolean. Master link to dnsmasq. Parse /etc/config/dhcp for dnsmasq
  70                 options. Forward domain such as "lan" and PTR records for DHCP
  71                 interfaces and their deligated subnets, IP4 and IP6.
  72
  73         option dnsmasq_only_local '0'
  74                 TODO: not yet implemented
  75                 Boolean. Restrict link to dnsmasq. DNS only to local host. Obscure
  76                 names of other connected hosts on the network. Example:
  77                 "drill -x 198.51.100.17  ~ IN PTR way-out.myrouter.lan"
  78                 "drill -x 192.168.10.1   ~ IN PTR guest-wifi.myrouter.lan"
  79                 "drill -x 192.168.10.201 ~ NODATA" (insted of james-laptop.lan)
  80
  81         option edns_size '1280'
  82                 Extended DNS is necessary for DNSSEC. However, it can run into MTU
  83                 issues. Use this size in bytes to manage drop outs.
  84
  85         option listen_port '53'
  86                 Port. Incoming. Where Unbound will listen for queries.
  87
  88         option localservice '1'
  89                 Boolean. Prevent DNS amplification attacks. Only provide access to
  90                 Unbound from subnets this machine has interfaces on.
  91
  92         option manual_conf '0'
  93                 Boolean. Skip all this UCI nonsense. Manually edit the
  94                 configuration. Make changes to /etc/unbound/unbound.conf.
  95
  96         option query_minimize '0'
  97                 Boolean. Enable a minor privacy option. Query only one name piece
  98                 at a time. Don't let each server know the next recursion.
  99
 100         option rebind_localhost '0'
 101                 Boolean. Prevent loopback "127.0.0.0/8" or "::1/128" responses.
 102                 These may used by black hole servers for good purposes like
 103                 ad-blocking or parental access control. Obviously these responses
 104                 also can be used to for bad purposes.
 105
 106         option rebind_protection '1'
 107                 Boolean. Prevent RFC 1918 Reponses from global DNS. Example a
 108                 poisoned reponse within "192.168.0.0/24" could be used to turn a
 109                 local browser into an external attack proxy server.
 110
 111         option recursion 'passive'
 112                 Unbound has numerous options for how it recurses. This UCI combines
 113                 them into "passive," "aggressive," or Unbound's own "default."
 114                 Passive is easy on resources, but slower until cache fills.
 115
 116         option resource 'small'
 117                 Unbound has numerous options for resources. This UCI gives "tiny,"
 118                 "small," "medium," and "large." Medium is most like the compiled
 119                 defaults with a bit of balancing. Tiny is close to the published
 120                 memory restricted configuration. Small 1/2 medium, and large 2x.
 121
 122         option root_age '30'
 123                 Days. >90 Disables. Age limit for Unbound root data like root
 124                 DNSSEC key. Unbound uses RFC 5011 to manage root key. This could
 125                 harm flash ROM. This activity is mapped to "tmpfs," but every so
 126                 often it needs to be copied back to flash for the next reboot.
 127
 128         option ttl_min '120'
 129                 Seconds. Minimum TTL in cache. Recursion can be expensive without
 130                 cache. A low TTL is normal for server migration. A low TTL can be
 131                 abused for snoop-vertising (DNS hit counts; recording query IP).
 132                 Typical to configure maybe 0~300, but 1800 is the maximum accepted.
 133
 134         option unbound_control '0'
 135                 Boolean. Enables unbound-control application access ports. Enabling
 136                 this without the unbound-control package installed is robust.
 137
 138         option validator '0'
 139                 Boolean. Enable DNSSEC. Unbound names this the "validator" module.
 140
 141         option validator_ntp '1'
 142                 Boolean. Disable DNSSEC time checks at boot. Once NTP confirms
 143                 global real time, then DNSSEC is restarted at full strength. Many
 144                 embedded devices don't have a real time power off clock. NTP needs
 145                 DNS to resolve servers. This works around the chicken-and-egg.
 146
 147         list domain_insecure
 148                 List. Domains or pointers that you wish to skip DNSSEC. Your DHCP
 149                 domains and pointers in dnsmasq will get this automatically.
 150