remove "EXAMPLE" section containing a minimal example unbound.conf; the sample

isn't suitable for OpenBSD and can cause confusion. ok jmc@ brad@

1 files changed, 93 insertions, 49 deletions

diff --git a/usr.sbin/unbound/doc/unbound.conf.5.in b/usr.sbin/unbound/doc/unbound.conf.5.in
index eeec7daaf73..364174b61db 100644
--- a/usr.sbin/unbound/doc/unbound.conf.5.in
+++ b/usr.sbin/unbound/doc/unbound.conf.5.in
@@ -1,4 +1,4 @@
-.TH "unbound.conf" "5" "Feb  2, 2012" "NLnet Labs" "unbound 1.4.16"
+.TH "unbound.conf" "5" "Dec  8, 2014" "NLnet Labs" "unbound 1.5.1"
 .\"
 .\" unbound.conf.5 -- unbound.conf manual
 .\"
@@ -8,14 +8,11 @@
 .\"
 .\"
 .SH "NAME"
-.LP
 .B unbound.conf
 \- Unbound configuration file.
 .SH "SYNOPSIS"
-.LP
 .B unbound.conf
 .SH "DESCRIPTION"
-.LP
 .B unbound.conf
 is used to configure
 \fIunbound\fR(8).
@@ -28,55 +25,18 @@ ignored as is whitespace at the beginning of a line.
 The utility 
 \fIunbound\-checkconf\fR(8)
 can be used to check unbound.conf prior to usage.
-.SH "EXAMPLE"
-An example config file is shown below. Copy this to /etc/unbound/unbound.conf
-and start the server with:
-.P
-.nf
-	$ unbound \-c /etc/unbound/unbound.conf 
-.fi
-.P
-Most settings are the defaults. Stop the server with:
-.P
-.nf
-	$ kill `cat /etc/unbound/unbound.pid`
-.fi
-.P
-Below is a minimal config file. The source distribution contains an extensive
-example.conf file with all the options.
-.P
-.nf
-# unbound.conf(5) config file for unbound(8).
-server:
-	directory: "/etc/unbound"
-	username: unbound
-	# make sure unbound can access entropy from inside the chroot.
-	# e.g. on linux the use these commands (on BSD, devfs(8) is used):
-	#      mount \-\-bind \-n /dev/random /etc/unbound/dev/random
-	# and  mount \-\-bind \-n /dev/log /etc/unbound/dev/log
-	chroot: "/etc/unbound"
-	# logfile: "/etc/unbound/unbound.log"  #uncomment to use logfile.
-	pidfile: "/etc/unbound/unbound.pid"
-	# verbosity: 1		# uncomment and increase to get more logging.
-	# listen on all interfaces, answer queries from the local subnet.
-	interface: 0.0.0.0
-	interface: ::0
-	access\-control: 10.0.0.0/8 allow
-	access\-control: 2001:DB8::/64 allow
-.fi
 .SH "FILE FORMAT"
-.LP
 There must be whitespace between keywords. Attribute keywords end with a colon ':'. An attribute
 is followed by its containing attributes, or a value.
 .P
 Files can be included using the
 .B include:
-directive. It can appear anywhere, and takes a single filename as an argument.
+directive. It can appear anywhere, it accepts a single file name as argument.
 Processing continues as if the text from the included file was copied into
 the config file at that point.  If also using chroot, using full path names
 for the included files works, relative pathnames for the included names work
 if the directory where the daemon is started equals its chroot/working 
-directory.
+directory.  Wildcards can be used to include multiple files, see \fIglob\fR(7).
 .SS "Server Options"
 These options are part of the
 .B server:
@@ -122,6 +82,9 @@ A port number can be specified with @port (without spaces between
 interface and port number), if not specified the default port (from
 \fBport\fR) is used.
 .TP
+.B ip\-address: \fI<ip address[@port]>
+Same as interface: (for easy of compatibility with nsd.conf).
+.TP
 .B interface\-automatic: \fI<yes or no>
 Detect source interface on UDP queries and copy them to replies.  This 
 feature is experimental, and needs support in your OS for particular socket
@@ -166,23 +129,28 @@ 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.
+to 0, or if do\-tcp is "no", no TCP queries to authoritative servers are done.
 .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.
+to 0, or if do\-tcp is "no", no TCP queries from clients are accepted.
 .TP
 .B edns\-buffer\-size: \fI<number>
 Number of bytes size to advertise as the EDNS reassembly buffer size.
 This is the value put into datagrams over UDP towards peers.  The actual
 buffer size is determined by msg\-buffer\-size (both for TCP and UDP).  Do
-not set lower than that value.  Default is 4096 which is RFC recommended.
+not set higher than that value.  Default is 4096 which is RFC recommended.
 If you have fragmentation reassembly problems, usually seen as timeouts,
 then a value of 1480 can fix it.  Setting to 512 bypasses even the most
 stringent path MTU problems, but is seen as extreme, since the amount
 of TCP fallback generated is excessive (probably also for this resolver,
 consider tuning the outgoing tcp number).
 .TP
+.B max\-udp\-size: \fI<number>
+Maximum UDP response size (not applied to TCP response).  65536 disables the
+udp response size maximum, and uses the choice from the client, always.
+Suggested values are 512 to 4096. Default is 4096. 
+.TP
 .B msg\-buffer\-size: \fI<number>
 Number of bytes size of the message buffers. Default is 65552 bytes, enough
 for 64 Kb packets, the maximum DNS message size. No message larger than this
@@ -220,6 +188,15 @@ The qps for short queries can be about (numqueriesperthread / 2)
 / (jostletimeout in whole seconds) qps per thread, about (1024/2)*5 = 2560
 qps by default.
 .TP
+.B delay\-close: \fI<msec>
+Extra delay for timeouted UDP ports before they are closed, in msec.
+Default is 0, and that disables it.  This prevents very delayed answer
+packets from the upstream (recursive) servers from bouncing against
+closed ports and setting off all sort of close-port counters, with
+eg. 1500 msec.  When timeouts happen you need extra sockets, it checks
+the ID and remote IP of packets, and unwanted packets are added to the
+unwanted packet counter.
+.TP
 .B so\-rcvbuf: \fI<number>
 If not 0, then set the SO_RCVBUF socket option to get more buffer
 space on UDP port 53 incoming queries.  So that short spikes on busy
@@ -242,6 +219,16 @@ linux unbound needs root permission to bypass the limit, or the admin
 can use sysctl net.core.wmem_max.  On BSD, Solaris changes are similar
 to so\-rcvbuf.
 .TP
+.B so\-reuseport: \fI<yes or no>
+If yes, then open dedicated listening sockets for incoming queries for each
+thread and try to set the SO_REUSEPORT socket option on each socket.  May
+distribute incoming queries to threads more evenly.  Default is no.  On Linux
+it is supported in kernels >= 3.9.  On other systems, FreeBSD, OSX it may
+also work.  You can enable it (on any platform and kernel),
+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 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,7 +271,9 @@ Enable or disable whether ip4 queries are answered or issued. Default is yes.
 .B do\-ip6: \fI<yes or no>
 Enable or disable whether ip6 queries are answered or issued. Default is yes.
 If disabled, queries are not answered on IPv6, and queries are not sent on
-IPv6 to the internet nameservers.
+IPv6 to the internet nameservers.  With this option you can disable the
+ipv6 transport for sending DNS traffic, it does not impact the contents of
+the DNS traffic, which may have ip4 and ip6 addresses in it.
 .TP
 .B do\-udp: \fI<yes or no>
 Enable or disable whether UDP queries are answered or issued. Default is yes.
@@ -326,7 +315,7 @@ a daemon. Default is yes.
 .B access\-control: \fI<IP netblock> <action>
 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 or \fIallow_snoop\fR.
+\fIallow\fR, \fIallow_snoop\fR, \fIdeny_non_local\fR or \fIrefuse_non_local\fR.
 .IP
 The action \fIdeny\fR stops queries from hosts from that netblock.
 .IP
@@ -355,6 +344,12 @@ By default only localhost is \fIallow\fRed, the rest is \fIrefuse\fRd.
 The default is \fIrefuse\fRd, because that is protocol\-friendly. The DNS 
 protocol is not designed to handle dropped packets due to policy, and 
 dropping may result in (possibly excessive) retried queries.
+.IP
+The deny_non_local and refuse_non_local settings are for hosts that are
+only allowed to query for the authoritative local\-data, they are not
+allowed full recursion but only the static data.  With deny_non_local,
+messages that are disallowed are dropped, with refuse_non_local they
+receive error code REFUSED.
 .TP
 .B chroot: \fI<directory>
 If chroot is enabled, you should pass the configfile (from the
@@ -492,7 +487,7 @@ unsigned to badly signed often. If turned off you run the risk of a
 downgrade attack that disables security for a zone. Default is on.
 .TP
 .B harden\-below\-nxdomain: \fI<yes or no>
-From draft-vixie-dnsext-resimprove, returns nxdomain to queries for a name
+From draft\-vixie\-dnsext\-resimprove, returns nxdomain to queries for a name
 below another name that is already known to be nxdomain.  DNSSEC mandates
 noerror for empty nonterminals, hence this is possible.  Very old software
 might return nxdomain for empty nonterminals (that usually happen for reverse
@@ -570,6 +565,18 @@ If yes, fetch the DNSKEYs earlier in the validation process, when a DS
 record is encountered.  This lowers the latency of requests.  It does use
 a little more CPU.  Also if the cache is set to 0, it is no use. Default is no.
 .TP
+.B rrset-roundrobin: \fI<yes or no>
+If yes, Unbound rotates RRSet order in response (the random number is taken
+from the query ID, for speed and thread safety).  Default is no.
+.TP
+.B minimal-responses: \fI<yes or no>
+If yes, Unbound doesn't insert authority/additional sections into response
+messages when those sections are not required.  This reduces response
+size significantly, and may avoid TCP fallback for some responses.
+This may cause a slight speedup.  The default is no, because the DNS
+protocol RFCs mandate these sections, and the additional content could
+be of use and save roundtrips for clients.
+.TP
 .B module\-config: \fI<"module names">
 Module configuration, a list of module names separated by spaces, surround
 the string with quotes (""). The modules can be validator, iterator.
@@ -734,6 +741,17 @@ Number of bytes size of the aggressive negative cache. Default is 1 megabyte.
 A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
 or gigabytes (1024*1024 bytes in a megabyte).
 .TP
+.B unblock\-lan\-zones: \fI<yesno>
+Default is disabled.  If enabled, then for private address space,
+the reverse lookups are no longer filtered.  This allows unbound when
+running as dns service on a host where it provides service for that host,
+to put out all of the queries for the 'lan' upstream.  When enabled,
+only localhost, 127.0.0.1 reverse and ::1 reverse zones are configured
+with default local zones.  Disable the option when unbound is running
+as a (DHCP-) DNS network resolver for a group of machines, where such
+lookups should be filtered (RFC compliance), this also stops potential
+data leakage about the local network to the upstream DNS servers.
+.TP
 .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,
@@ -850,6 +868,7 @@ records are provided.
 Reverse data for zones 0.in\-addr.arpa, 254.169.in\-addr.arpa, 
 2.0.192.in\-addr.arpa (TEST NET 1), 100.51.198.in\-addr.arpa (TEST NET 2),
 113.0.203.in\-addr.arpa (TEST NET 3), 255.255.255.255.in\-addr.arpa.
+And from 64.100.in\-addr.arpa to 127.100.in\-addr.arpa (Shared Address Space).
 .TP 10
 \h'5'\fIreverse RFC4291 IP6 unspecified\fR
 Reverse data for zone 
@@ -979,6 +998,12 @@ This option is by default off.  If enabled it performs NS set priming,
 which is similar to root hints, where it starts using the list of nameservers 
 currently published by the zone.  Thus, if the hint list is slightly outdated,
 the resolver picks up a correct list online.
+.TP
+.B stub\-first: \fI<yes or no>
+If enabled, a query is attempted without the stub clause if it fails.
+The data could not be retrieved and would have caused SERVFAIL because
+the servers are unreachable, instead it is tried without this clause.
+The default is no.
 .SS "Forward Zone Options"
 .LP
 There may be multiple
@@ -1003,6 +1028,12 @@ Name of server to forward to. Is itself resolved before it is used.
 .B forward\-addr: \fI<IP address>
 IP address of server to forward to. Can be IP 4 or IP 6.
 To use a nondefault port for DNS communication append '@' with the port number.
+.TP
+.B forward\-first: \fI<yes or no>
+If enabled, a query is attempted without the forward clause if it fails.
+The data could not be retrieved and would have caused SERVFAIL because
+the servers are unreachable, instead it is tried without this clause.
+The default is no.
 .SS "Python Module Options"
 .LP
 The
@@ -1015,6 +1046,19 @@ and the word "python" has to be put in the \fBmodule\-config:\fR option
 .TP
 .B python\-script: \fI<python file>\fR
 The script file to load. 
+.SS "DNS64 Module Options"
+.LP
+The dns64 module must be configured in the \fBmodule\-config:\fR "dns64
+validator iterator" directive and be compiled into the daemon to be
+enabled.  These settings go in the \fBserver:\fR section.
+.TP
+.B dns64\-prefix: \fI<IPv6 prefix>\fR
+This sets the DNS64 prefix to use to synthesize AAAA records with.
+It must be /96 or shorter.  The default prefix is 64:ff9b::/96.
+.TP
+.B dns64\-synthall: \fI<yes or no>\fR
+Debug option, default no.  If enabled, synthesize all AAAA records
+despite the presence of actual AAAA records.
 .SH "MEMORY CONTROL EXAMPLE"
 In the example config settings below memory usage is reduced. Some service
 levels are lower, notable very large data and a high TCP load are no longer