MFH (r287917, r287918, r289063): upgrade to latest Unbound

MFH (r283301, r289592, r291582): rc script improvements
MFH (r287880): respect manually configured forwarders when using DHCP
MFH (r289321): deconfuse man page

PR:		184047 203580 204931

1 files changed, 107 insertions, 12 deletions

diff --git a/contrib/unbound/doc/unbound.conf.5 b/contrib/unbound/doc/unbound.conf.5
index c2637aa..990a0a6 100644
--- a/contrib/unbound/doc/unbound.conf.5
+++ b/contrib/unbound/doc/unbound.conf.5
@@ -1,4 +1,4 @@
-.TH "unbound.conf" "5" "Mar 10, 2015" "NLnet Labs" "unbound 1.5.3"
+.TH "unbound.conf" "5" "Oct  6, 2015" "NLnet Labs" "unbound 1.5.5"
 .\"
 .\" unbound.conf.5 -- unbound.conf manual
 .\"
@@ -164,12 +164,14 @@ By default only ports above 1024 that have not been assigned by IANA are used.
 Give a port number or a range of the form "low\-high", without spaces.
 .TP
 .B outgoing\-num\-tcp: \fI<number>
-Number of outgoing TCP buffers to allocate per thread. Default is 10. If set
-to 0, or if do\-tcp is "no", no TCP queries to authoritative servers are done.
+Number of outgoing TCP buffers to allocate per thread. Default is 10. If
+set to 0, or if do\-tcp is "no", no TCP queries to authoritative servers
+are done.  For larger installations increasing this value is a good idea.
 .TP
 .B incoming\-num\-tcp: \fI<number>
-Number of incoming TCP buffers to allocate per thread. Default is 10. If set
-to 0, or if do\-tcp is "no", no TCP queries from clients are accepted.
+Number of incoming TCP buffers to allocate per thread. Default is
+10. If set to 0, or if do\-tcp is "no", no TCP queries from clients are
+accepted. For larger installations increasing this value is a good idea.
 .TP
 .B edns\-buffer\-size: \fI<number>
 Number of bytes size to advertise as the EDNS reassembly buffer size.
@@ -265,6 +267,16 @@ it then attempts to open the port and passes the option if it was available
 at compile time, if that works it is used, if it fails, it continues
 silently (unless verbosity 3) without the option.
 .TP
+.B ip\-transparent: \fI<yes or no>
+If yes, then use IP_TRANSPARENT socket option on sockets where unbound
+is listening for incoming traffic.  Default no.  Allows you to bind to
+non\-local interfaces.  For example for non\-existant IP addresses that
+are going to exist later on, with host failover configuration.  This is
+a lot like interface\-automatic, but that one services all interfaces
+and with this option you can select which (future) interfaces unbound
+provides service on.  This option needs unbound to be started with root
+permissions on some systems.
+.TP
 .B rrset\-cache\-size: \fI<number>
 Number of bytes size of the RRset cache. Default is 4 megabytes.
 A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
@@ -284,12 +296,16 @@ trust (very large) TTL values.
 .TP
 .B cache\-min\-ttl: \fI<seconds>
 Time to live minimum for RRsets and messages in the cache. Default is 0.
-If the the minimum kicks in, the data is cached for longer than the domain
+If the minimum kicks in, the data is cached for longer than the domain
 owner intended, and thus less queries are made to look up the data.
 Zero makes sure the data in the cache is as the domain owner intended,
 higher values, especially more than an hour or so, can lead to trouble as 
 the data in the cache does not match up with the actual data any more.
 .TP
+.B cache\-max\-negative\-ttl: \fI<seconds>
+Time to live maximum for negative responses, these have a SOA in the
+authority section that is limited in time.  Default is 3600.
+.TP
 .B infra\-host\-ttl: \fI<seconds>
 Time to live for entries in the host cache. The host cache contains 
 roundtrip timing, lameness and EDNS support information. Default is 900.
@@ -357,6 +373,7 @@ a daemon. Default is yes.
 The netblock is given as an IP4 or IP6 address with /size appended for a 
 classless network block. The action can be \fIdeny\fR, \fIrefuse\fR, 
 \fIallow\fR, \fIallow_snoop\fR, \fIdeny_non_local\fR or \fIrefuse_non_local\fR.
+The most specific netblock match is used, if none match \fIdeny\fR is used.
 .IP
 The action \fIdeny\fR stops queries from hosts from that netblock.
 .IP
@@ -464,7 +481,7 @@ kill \-HUP `cat /var/unbound/unbound.pid`
 .fi
 triggers a reload,
 .nf
-kill \-QUIT `cat /var/unbound/unbound.pid` 
+kill \-TERM `cat /var/unbound/unbound.pid` 
 .fi
 gracefully terminates.
 .TP
@@ -548,6 +565,13 @@ extra query load that is generated.  Experimental option.
 If you enable it consider adding more numbers after the target\-fetch\-policy
 to increase the max depth that is checked to.
 .TP
+.B harden\-algo\-downgrade: \fI<yes or no>
+Harden against algorithm downgrade when multiple algorithms are
+advertised in the DS record.  If no, allows the weakest algorithm to
+validate the zone.  Default is no.  Zone signers must produce zones
+that allow this feature to work, but sometimes they do not, and turning
+this option off avoids that validation failure.
+.TP
 .B use\-caps\-for\-id: \fI<yes or no>
 Use 0x20\-encoded random bits in the query to foil spoof attempts.
 This perturbs the lowercase and uppercase of query names sent to 
@@ -555,6 +579,12 @@ authority servers and checks if the reply still has the correct casing.
 Disabled by default. 
 This feature is an experimental implementation of draft dns\-0x20.
 .TP
+.B caps\-whitelist: \fI<domain>
+Whitelist the domain so that it does not receive caps\-for\-id perturbed
+queries.  For domains that do not support 0x20 and also fail with fallback
+because they keep sending different answers, like some load balancers.
+Can be given multiple times, for different domains.
+.TP
 .B private\-address: \fI<IP address or subnet>
 Give IPv4 of IPv6 addresses or classless subnets. These are addresses
 on your private network, and are not allowed to be returned for public
@@ -655,14 +685,19 @@ It is possible to use wildcards with this statement, the wildcard is
 expanded on start and on reload.
 .TP
 .B dlv\-anchor\-file: \fI<filename>
+This option was used during early days DNSSEC deployment when no parent-side
+DS record registrations were easily available.  Nowadays, it is best to have
+DS records registered with the parent zone (many top level zones are signed).
 File with trusted keys for DLV (DNSSEC Lookaside Validation). Both DS and
 DNSKEY entries can be used in the file, in the same format as for
 \fItrust\-anchor\-file:\fR statements. Only one DLV can be configured, more
 would be slow. The DLV configured is used as a root trusted DLV, this 
 means that it is a lookaside for the root. Default is "", or no dlv anchor file.
+DLV is going to be decommissioned.  Please do not use it any more.
 .TP
 .B dlv\-anchor: \fI<"Resource Record">
 Much like trust\-anchor, this is a DLV anchor with the DS or DNSKEY inline.
+DLV is going to be decommissioned.  Please do not use it any more.
 .TP
 .B domain\-insecure: \fI<domain name>
 Sets domain name to be insecure, DNSSEC chain of trust is ignored towards
@@ -767,6 +802,10 @@ mechanism work with zones that perform regular (non\-5011) rollovers.
 The default is 366 days.  The value 0 does not remove missing anchors,
 as per the RFC.
 .TP
+.B permit\-small\-holddown: \fI<yes or no>
+Debug option that allows the autotrust 5011 rollover timers to assume
+very small values.  Default is no.
+.TP
 .B key\-cache\-size: \fI<number>
 Number of bytes size of the key cache. Default is 4 megabytes.
 A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
@@ -796,10 +835,10 @@ data leakage about the local network to the upstream DNS servers.
 .B local\-zone: \fI<zone> <type>
 Configure a local zone. The type determines the answer to give if
 there is no match from local\-data. The types are deny, refuse, static,
-transparent, redirect, nodefault, typetransparent, inform, and are explained
-below. After that the default settings are listed. Use local\-data: to
-enter data into the local zone. Answers for local zones are authoritative
-DNS answers. By default the zones are class IN.
+transparent, redirect, nodefault, typetransparent, inform, inform_deny,
+and are explained below. After that the default settings are listed. Use
+local\-data: to enter data into the local zone. Answers for local zones
+are authoritative DNS answers. By default the zones are class IN.
 .IP
 If you need more complicated authoritative data, with referrals, wildcards,
 CNAME/DNAME support, or DNSSEC authoritative service, setup a stub\-zone for
@@ -853,11 +892,16 @@ info: zonename inform IP@port queryname type class.  This option can be
 used for normal resolution, but machines looking up infected names are
 logged, eg. to run antivirus on them.
 .TP 10
+\h'5'\fIinform_deny\fR 
+The query is dropped, like 'deny', and logged, like 'inform'.  Ie. find
+infected machines without answering the queries.
+.TP 10
 \h'5'\fInodefault\fR 
 Used to turn off default contents for AS112 zones. The other types
 also turn off default contents for the zone. The 'nodefault' option 
 has no other effect than turning off default contents for the 
-given zone.
+given zone.  Use \fInodefault\fR if you use exactly that zone, if you want to
+use a subzone, use \fItransparent\fR.
 .P
 The default zones are localhost, reverse 127.0.0.1 and ::1, and the AS112
 zones. The AS112 zones are reverse DNS zones for private use and reserved
@@ -959,6 +1003,51 @@ it as detailed in the stub zone section below.
 Configure local data shorthand for a PTR record with the reversed IPv4 or
 IPv6 address and the host name.  For example "192.0.2.4 www.example.com".
 TTL can be inserted like this: "2001:DB8::4 7200 www.example.com"
+.TP 5
+.B ratelimit: \fI<number or 0>
+Enable ratelimiting of queries sent to nameserver for performing recursion.
+If 0, the default, it is disabled.  This option is experimental at this time.
+The ratelimit is in queries per second that are allowed.  More queries are
+turned away with an error (servfail).  This stops recursive floods, eg. random
+query names, but not spoofed reflection floods.  Cached responses are not
+ratelimited by this setting.  The zone of the query is determined by examining
+the nameservers for it, the zone name is used to keep track of the rate.
+For example, 1000 may be a suitable value to stop the server from being
+overloaded with random names, and keeps unbound from sending traffic to the
+nameservers for those zones.
+.TP 5
+.B ratelimit\-size: \fI<memory size>
+Give the size of the data structure in which the current ongoing rates are
+kept track in.  Default 4m.  In bytes or use m(mega), k(kilo), g(giga).
+The ratelimit structure is small, so this data structure likely does
+not need to be large.
+.TP 5
+.B ratelimit\-slabs: \fI<number>
+Give power of 2 number of slabs, this is used to reduce lock contention
+in the ratelimit tracking data structure.  Close to the number of cpus is
+a fairly good setting.
+.TP 5
+.B ratelimit\-factor: \fI<number>
+Set the amount of queries to rate limit when the limit is exceeded.
+If set to 0, all queries are dropped for domains where the limit is
+exceeded.  If set to another value, 1 in that number is allowed through
+to complete.  Default is 10, allowing 1/10 traffic to flow normally.
+This can make ordinary queries complete (if repeatedly queried for),
+and enter the cache, whilst also mitigiting the traffic flow by the
+factor given.
+.TP 5
+.B ratelimit\-for\-domain: \fI<domain> <number qps>
+Override the global ratelimit for an exact match domain name with the listed
+number.  You can give this for any number of names.  For example, for
+a top\-level\-domain you may want to have a higher limit than other names.
+.TP 5
+.B ratelimit\-below\-domain: \fI<domain> <number qps>
+Override the global ratelimit for a domain name that ends in this name.
+You can give this multiple times, it then describes different settings
+in different parts of the namespace.  The closest matching suffix is used
+to determine the qps limit.  The rate for the exact matching domain name
+is not changed, use ratelimit\-for\-domain to set that, you might want
+to use different settings for a top\-level\-domain and subdomains.
 .SS "Remote Control Options"
 In the
 .B remote\-control:
@@ -1041,6 +1130,12 @@ bit on replies for the private zone (authoritative servers do not set the
 AD bit).  This setup makes unbound capable of answering queries for the 
 private zone, and can even set the AD bit ('authentic'), but the AA 
 ('authoritative') bit is not set on these replies. 
+.P
+Consider adding \fBserver:\fR statements for \fBdomain\-insecure:\fR and
+for \fBlocal\-zone:\fI name nodefault\fR for the zone if it is a locally
+served zone.  The insecure clause stops DNSSEC from invalidating the
+zone.  The local zone nodefault (or \fItransparent\fR) clause makes the
+(reverse\-) zone bypass unbound's filtering of RFC1918 zones.
 .TP
 .B name: \fI<domain name>
 Name of the stub zone.