summaryrefslogtreecommitdiff
path: root/usr.sbin/unbound/doc
diff options
context:
space:
mode:
authorFlorian Obser <florian@cvs.openbsd.org>2018-02-07 00:24:34 +0000
committerFlorian Obser <florian@cvs.openbsd.org>2018-02-07 00:24:34 +0000
commit57b80dd8cd9a6b27ad0b5a1e837d4d892df5d860 (patch)
tree915d90c97934e2a63d97cb28ecef928dd0cf74c7 /usr.sbin/unbound/doc
parent12e51d6e355308d9ca1ad65f3ef8be112f9e4d8c (diff)
update to unbound 1.6.8, testing millert, OK sthen
Diffstat (limited to 'usr.sbin/unbound/doc')
-rw-r--r--usr.sbin/unbound/doc/Changelog163
-rw-r--r--usr.sbin/unbound/doc/example.conf.in32
-rw-r--r--usr.sbin/unbound/doc/libunbound.3.in14
-rw-r--r--usr.sbin/unbound/doc/requirements.txt2
-rw-r--r--usr.sbin/unbound/doc/unbound-control.8.in52
-rw-r--r--usr.sbin/unbound/doc/unbound.conf.5.in37
6 files changed, 291 insertions, 9 deletions
diff --git a/usr.sbin/unbound/doc/Changelog b/usr.sbin/unbound/doc/Changelog
index 39a3a2b7f4a..05929c48d2e 100644
--- a/usr.sbin/unbound/doc/Changelog
+++ b/usr.sbin/unbound/doc/Changelog
@@ -1,5 +1,166 @@
+19 January 2018: Wouter
+ - tag 1.6.8 for release with CVE fix.
+ - trunk has 1.6.9 with fix and previous commits.
+ - patch for CVE-2017-15105: vulnerability in the processing of
+ wildcard synthesized NSEC records.
+
+4 January 2018: Ralph
+ - Copy query and correctly set flags on REFUSED answers when cache
+ snooping is not allowed.
+
+3 January 2018: Ralph
+ - Fix queries being leaked above stub when refetching glue.
+
+2 January 2017: Wouter
+ - Fix that DS queries with referral replies are answered straight
+ away, without a repeat query picking the DS from cache.
+ The correct reply should have been an answer, the reply is fixed
+ by the scrubber to have the answer in the answer section.
+ - Remove clang optimizer disable,
+ Fix that expiration date checks don't fail with clang -O2.
+
+15 December 2017: Wouter
+ - Fix timestamp failure because of clang optimizer failure, by
+ disabling -O2 when the compiler --version is clang.
+ - iana port update.
+ - Also disable -flto for clang, to make incep-expi signature check
+ work.
+
+12 December 2017: Ralph
+ - Fix qname-minimisation documentation (A QTYPE, not NS)
+
+12 December 2017: Wouter
+ - authzone work, transfer connect.
+
+7 December 2017: Ralph
+ - Check whether --with-libunbound-only is set when using --with-nettle
+ or --with-nss.
+
+4 December 2017: Wouter
+ - Fix link failure on OmniOS.
+
+1 December 2017: Wouter
+ - auth zone work.
+
+30 November 2017: Wouter
+ - Fix #3299 - forward CNAME daisy chain is not working
+
+14 November 2017: Wouter
+ - Fix #2882: Unbound behaviour changes (wrong) when domain-insecure is
+ set for stub zone. It no longer searches for DNSSEC information.
+ - auth xfer work on probe timer and lookup.
+
+13 November 2017: Wouter
+ - Fix #2801: Install libunbound.pc.
+ - Fix qname minimisation to send AAAA queries at zonecut like type A.
+ - reverted AAAA change.
+
+7 November 2017: Wouter
+ - Fix #2492: Documentation libunbound.
+
+3 November 2017: Wouter
+ - Fix #2362: TLS1.3/openssl-1.1.1 not working.
+ - Fix #2034 - Autoconf and -flto.
+ - Fix #2141 - for libsodium detect lack of entropy in chroot, print
+ a message and exit.
+
+2 November 2017: Wouter
+ - Fix #1913: ub_ctx_config is under circumstances thread-safe.
+ - make ip-transparent option work on OpenBSD.
+
+31 October 2017: Wouter
+ - Document that errno is left informative on libunbound config read
+ fail.
+ - lexer output.
+ - iana port update.
+
+25 October 2017: Ralph
+ - Fixed libunbound manual typo.
+ - Fix #1949: [dnscrypt] make provider name mismatch more obvious.
+ - Fix #2031: Double included headers
+
+24 October 2017: Ralph
+ - Update B root ipv4 address.
+
+19 October 2017: Wouter
+ - authzone work, probe timer setup.
+
+18 October 2017: Wouter
+ - lint for recent authzone commit.
+
+17 October 2017: Wouter
+ - Fix #1749: With harden-referral-path: performance drops, due to
+ circular dependency in NS and DS lookups.
+ - [dnscrypt] prevent dnscrypt-secret-key, dnscrypt-provider-cert
+ duplicates
+ - [dnscrypt] introduce dnscrypt-provider-cert-rotated option,
+ from Manu Bretelle.
+ This option allows handling multiple cert/key pairs while only
+ distributing some of them.
+ In order to reliably match a client magic with a given key without
+ strong assumption as to how those were generated, we need both key and
+ cert. Likewise, in order to know which ES version should be used.
+ On the other hand, when rotating a cert, it can be desirable to only
+ serve the new cert but still be able to handle clients that are still
+ using the old certs's public key.
+ The `dnscrypt-provider-cert-rotated` allow to instruct unbound to not
+ publish the cert as part of the DNS's provider_name's TXT answer.
+ - Better documentation for cache-max-negative-ttl.
+ - Work on local root zone code.
+
+10 October 2017: Wouter
+ - tag 1.6.7
+ - trunk has version 1.6.8.
+
+6 October 2017: Wouter
+ - Fix spelling in unbound-control man page.
+
+5 October 2017: Wouter
+ - Fix trust-anchor-signaling works in libunbound.
+ - Fix some more crpls in testdata for different signaling default.
+ - tag 1.6.7rc1
+
+5 October 2017: Ralph
+ - Set trust-anchor-signaling default to yes
+ - Use RCODE from A query on DNS64 synthesized answer.
+
+2 October 2017: Wouter
+ - Fix param unused warning for windows exportsymbol compile.
+
+25 September 2017: Ralph
+ - Fix #1450: Generate again patch contrib/aaaa-filter-iterator.patch
+ (by Danilo G. Baio).
+
+21 September 2017: Ralph
+ - Log name of looping module
+
+19 September 2017: Wouter
+ - use a cachedb answer even if it's "expired" when serve-expired is yes
+ (patch from Jinmei Tatuya).
+ - trigger refetching of the answer in that case (this will bypass
+ cachedb lookup)
+ - allow storing a 0-TTL answer from cachedb in the in-memory message
+ cache when serve-expired is yes
+ - Fix DNSCACHE_STORE_ZEROTTL to be bigger than 0xffff.
+
+18 September 2017: Ralph
+ - Fix #1400: allowing use of global cache on ECS-forwarding unless
+ always-forward.
+
+18 September 2017: Wouter
+ - tag 1.6.6 (is 1.6.6rc2)
+ - Fix that looping modules always stop the query, and don't pass
+ control.
+ - Fix #1435: Please allow UDP to be disabled separately upstream and
+ downstream.
+ - Fix #1440: [dnscrypt] client nonce cache.
+
+15 September 2017: Wouter
+ - Fix unbound-host to report error for DNSSEC state of failed lookups.
+ - Spelling fixes, from Josh Soref.
+
13 September 2017: Wouter
- - tag 1.6.6rc2
+ - tag 1.6.6rc2, became 1.6.6 on 18 sep. trunk 1.6.7 in development.
12 September 2017: Wouter
- Add dns64 for client-subnet in unbound-checkconf.
diff --git a/usr.sbin/unbound/doc/example.conf.in b/usr.sbin/unbound/doc/example.conf.in
index e7978b79c89..2d14d69c0f9 100644
--- a/usr.sbin/unbound/doc/example.conf.in
+++ b/usr.sbin/unbound/doc/example.conf.in
@@ -199,6 +199,10 @@ server:
# upstream connections use TCP only (and no UDP), "yes" or "no"
# useful for tunneling scenarios, default no.
# tcp-upstream: no
+
+ # upstream connections also use UDP (even if do-udp is no).
+ # useful if if you want UDP upstream, but don't provide UDP downstream.
+ # udp-upstream-without-downstream: no
# Maximum segment size (MSS) of TCP socket on which the server
# responds to queries. Default is 0, system default MSS.
@@ -367,7 +371,7 @@ server:
# Sent minimum amount of information to upstream servers to enhance
# privacy. Only sent minimum required labels of the QNAME and set QTYPE
- # to NS when possible.
+ # to A when possible.
# qname-minimisation: no
# QNAME minimisation in strict mode. Do not fall-back to sending full
@@ -512,7 +516,7 @@ server:
# that set CD but cannot validate themselves.
# ignore-cd-flag: no
- # Serve expired reponses from cache, with TTL 0 in the response,
+ # Serve expired responses from cache, with TTL 0 in the response,
# and then attempt to fetch the data afresh.
# serve-expired: no
@@ -804,6 +808,30 @@ remote-control:
# name: "example.org"
# forward-host: fwd.example.com
+# Authority zones
+# The data for these zones is kept locally, from a file or downloaded.
+# The data can be served to downstream clients, or used instead of the
+# upstream (which saves a lookup to the upstream). The first example
+# has a copy of the root for local usage. The second serves example.org
+# authoritatively. zonefile: reads from file (and writes to it if you also
+# download it), master: fetches with AXFR, url: fetches zonefile over http.
+# auth-zone:
+# name: "."
+# for-downstream: no
+# for-upstream: yes
+# master: b.root-servers.net
+# master: c.root-servers.net
+# master: e.root-servers.net
+# master: f.root-servers.net
+# master: g.root-servers.net
+# master: k.root-servers.net
+# auth-zone:
+# name: "example.org"
+# for-downstream: yes
+# for-upstream: yes
+# zonefile: "example.org.zone"
+# url: "http://www.example.com/example.org.zone"
+
# Views
# Create named views. Name must be unique. Map views to requests using
# the access-control-view option. Views can contain zero or more local-zone
diff --git a/usr.sbin/unbound/doc/libunbound.3.in b/usr.sbin/unbound/doc/libunbound.3.in
index fbf3cd832af..8245f70cd84 100644
--- a/usr.sbin/unbound/doc/libunbound.3.in
+++ b/usr.sbin/unbound/doc/libunbound.3.in
@@ -150,7 +150,8 @@
is an implementation of a DNS resolver, that does caching and
DNSSEC validation. This is the library API, for using the \-lunbound library.
The server daemon is described in \fIunbound\fR(8).
-The library can be used to convert hostnames to ip addresses, and back,
+The library works independent from a running unbound server, and
+can be used to convert hostnames to ip addresses, and back,
and obtain other information from the DNS. The library performs public\-key
validation of results with DNSSEC.
.P
@@ -162,7 +163,7 @@ and deleting it with
It can be created and deleted at any time. Creating it anew removes any
previous configuration (such as trusted keys) and clears any cached results.
.P
-The functions are thread\-safe, and a context an be used in a threaded (as
+The functions are thread\-safe, and a context can be used in a threaded (as
well as in a non\-threaded) environment. Also resolution (and validation)
can be performed blocking and non\-blocking (also called asynchronous).
The async method returns from the call immediately, so that processing
@@ -203,7 +204,10 @@ without trailing ':'. The returned value must be free(2)d by the caller.
A power\-user interface that lets you specify an unbound config file, see
\fIunbound.conf\fR(5), which is read for configuration. Not all options are
relevant. For some specific options, such as adding trust anchors, special
-routines exist.
+routines exist. This function is thread\-safe only if a single instance of
+ub_ctx* exists in the application. If several instances exist the
+application has to ensure that ub_ctx_config is not called in parallel by
+the different instances.
.TP
.B ub_ctx_set_fwd
Set machine to forward DNS queries to, the caching resolver to use.
@@ -407,6 +411,10 @@ returns NULL on an error (a malloc failure).
returns true if some information may be available, false otherwise.
.B ub_fd
returns a file descriptor or \-1 on error.
+.B ub_ctx_config
+and
+.B ub_ctx_resolvconf
+attempt to leave errno informative on a function return with file read failure.
.SH "SEE ALSO"
\fIunbound.conf\fR(5),
\fIunbound\fR(8).
diff --git a/usr.sbin/unbound/doc/requirements.txt b/usr.sbin/unbound/doc/requirements.txt
index a66962d4a40..b643cec17d3 100644
--- a/usr.sbin/unbound/doc/requirements.txt
+++ b/usr.sbin/unbound/doc/requirements.txt
@@ -81,7 +81,7 @@ o Too many Features.
5. Choices
----------
-o rfc2181 decourages duplicates RRs in RRsets. unbound does not create
+o rfc2181 discourages duplicates RRs in RRsets. unbound does not create
duplicates, but when presented with duplicates on the wire from the
authoritative servers, does not perform duplicate removal.
It does do some rrsig duplicate removal, in the msgparser, for dnssec qtype
diff --git a/usr.sbin/unbound/doc/unbound-control.8.in b/usr.sbin/unbound/doc/unbound-control.8.in
index 66ea690390a..2f3fbf9e4f1 100644
--- a/usr.sbin/unbound/doc/unbound-control.8.in
+++ b/usr.sbin/unbound/doc/unbound-control.8.in
@@ -337,6 +337,19 @@ number of queries that were successfully answered using a cache lookup
.I threadX.num.cachemiss
number of queries that needed recursive processing
.TP
+.I threadX.num.dnscrypt.crypted
+number of queries that were encrypted and successfully decapsulated by dnscrypt.
+.TP
+.I threadX.num.dnscrypt.cert
+number of queries that were requesting dnscrypt certificates.
+.TP
+.I threadX.num.dnscrypt.cleartext
+number of queries received on dnscrypt port that were cleartext and not a
+request for certificates.
+.TP
+.I threadX.num.dnscrypt.malformed
+number of request that were neither cleartext, not valid dnscrypt messages.
+.TP
.I threadX.num.prefetch
number of cache prefetches performed. This number is included in
cachehits, as the original query had the unprefetched answer from cache,
@@ -393,6 +406,18 @@ summed over threads.
.I total.num.cachemiss
summed over threads.
.TP
+.I total.num.dnscrypt.crypted
+summed over threads.
+.TP
+.I total.num.dnscrypt.cert
+summed over threads.
+.TP
+.I total.num.dnscrypt.cleartext
+summed over threads.
+.TP
+.I total.num.dnscrypt.malformed
+summed over threads.
+.TP
.I total.num.prefetch
summed over threads.
.TP
@@ -439,6 +464,12 @@ Memory in bytes in use by the RRset cache.
.I mem.cache.message
Memory in bytes in use by the message cache.
.TP
+.I mem.cache.dnscrypt_shared_secret
+Memory in bytes in use by the dnscrypt shared secrets cache.
+.TP
+.I mem.cache.dnscrypt_nonce
+Memory in bytes in use by the dnscrypt nonce cache.
+.TP
.I mem.mod.iterator
Memory in bytes in use by the iterator module.
.TP
@@ -497,6 +528,14 @@ These queries are also included in the num.query.edns.present number.
The number of queries that are turned away from being send to nameserver due to
ratelimiting.
.TP
+.I num.query.dnscrypt.shared_secret.cachemiss
+The number of dnscrypt queries that did not find a shared secret in the cache.
+The can be use to compute the shared secret hitrate.
+.TP
+.I num.query.dnscrypt.replay
+The number of dnscrypt queries that found a nonce hit in the nonce cache and
+hence are considered a query replay.
+.TP
.I num.answer.rcode.NXDOMAIN
The number of answers to queries, from cache or from recursion, that had the
return code NXDOMAIN. Also printed for the other return codes.
@@ -546,6 +585,19 @@ timing and protocol support information.
.I key.cache.count
The number of items in the key cache. These are DNSSEC keys, one item
per delegation point, and their validation status.
+.TP
+.I dnscrypt_shared_secret.cache.count
+The number of items in the shared secret cache. These are precomputed shared
+secrets for a given client public key/server secret key pair. Shared secrets
+are CPU intensive and this cache allows unbound to avoid recomputing the
+shared secret when multiple dnscrypt queries are sent from the same client.
+.TP
+.I dnscrypt_nonce.cache.count
+The number of items in the client nonce cache. This cache is used to prevent
+dnscrypt queries replay. The client nonce must be unique for each client public
+key/server secret key pair. This cache should be able to host QPS * `replay
+window` interval keys to prevent replay of a query during `replay window`
+seconds.
.SH "FILES"
.TP
.I @ub_conf_file@
diff --git a/usr.sbin/unbound/doc/unbound.conf.5.in b/usr.sbin/unbound/doc/unbound.conf.5.in
index fcad8017d73..7dc507c86a7 100644
--- a/usr.sbin/unbound/doc/unbound.conf.5.in
+++ b/usr.sbin/unbound/doc/unbound.conf.5.in
@@ -295,6 +295,7 @@ the data in the cache does not match up with the actual data any more.
.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.
+This applies to nxdomain and nodata answers.
.TP
.B infra\-host\-ttl: \fI<seconds>
Time to live for entries in the host cache. The host cache contains
@@ -356,6 +357,11 @@ negotiation between Unbound and other servers.
Enable or disable whether the upstream queries use TCP only for transport.
Default is no. Useful in tunneling scenarios.
.TP
+.B udp\-upstream\-without\-downstream: \fI<yes or no>
+Enable udp upstream even if do-udp is no. Default is no, and this does not
+change anything. Useful for TLS service providers, that want no udp downstream
+but use udp to fetch data upstream.
+.TP
.B ssl\-upstream: \fI<yes or no>
Enabled or disable whether the upstream queries use SSL only for transport.
Default is no. Useful in tunneling scenarios. The SSL contains plain DNS in
@@ -641,7 +647,7 @@ Can be given multiple times, for different domains.
.TP
.B qname\-minimisation: \fI<yes or no>
Send minimum amount of information to upstream servers to enhance privacy.
-Only sent minimum required labels of the QNAME and set QTYPE to NS when
+Only sent minimum required labels of the QNAME and set QTYPE to A when
possible. Best effort approach; full QNAME and original QTYPE will be sent when
upstream replies with a RCODE other than NOERROR, except when receiving
NXDOMAIN from a DNSSEC signed zone. Default is off.
@@ -1343,6 +1349,9 @@ forward the queries to. The servers listed as \fBforward\-host:\fR and
those servers are not authority servers, but are (just like unbound is)
recursive servers too; unbound does not perform recursion itself for the
forward zone, it lets the remote server do it. Class IN is assumed.
+CNAMEs are chased by unbound itself, asking the remote server for every
+name in the indirection chain, to protect the local cache from illegal
+indirect referenced items.
A forward\-zone entry with name "." and a forward\-addr target will
forward all queries to that other server (unless it can answer from
the cache).
@@ -1464,6 +1473,19 @@ times.
Path to the certificate related to the \fBdnscrypt\-secret\-key\fRs.
This option may be specified multiple times.
.TP
+.B dnscrypt\-provider\-cert\-rotated: \fI<path to cert file>\fR
+Path to a certificate that we should be able to serve existing connection from
+but do not want to advertise over \fBdnscrypt\-provider\fR's TXT record certs
+distribution.
+A typical use case is when rotating certificates, existing clients may still use
+the client magic from the old cert in their queries until they fetch and update
+the new cert. Likewise, it would allow to prime the new cert/key without
+distributing the new cert yet, this can be useful when using a network of
+servers using anycast and on which the configuration may not get updated at the
+exact same time. By priming the cert, the servers can handle both old and new
+certs traffic while distributing only one.
+This option may be specified multiple times.
+.TP
.B dnscrypt\-shared\-secret\-cache\-size: \fI<memory size>
Give the size of the data structure in which the shared secret keys are kept
in. Default 4m. In bytes or use m(mega), k(kilo), g(giga).
@@ -1474,6 +1496,17 @@ using the same public key. It saves a substantial amount of CPU.
Give power of 2 number of slabs, this is used to reduce lock contention
in the dnscrypt shared secrets cache. Close to the number of cpus is
a fairly good setting.
+.TP
+.B dnscrypt\-nonce\-cache\-size: \fI<memory size>
+Give the size of the data structure in which the client nonces are kept in.
+Default 4m. In bytes or use m(mega), k(kilo), g(giga).
+The nonce cache is used to prevent dnscrypt message replaying. Client nonce
+should be unique for any pair of client pk/server sk.
+.TP
+.B dnscrypt\-nonce\-cache\-slabs: \fI<number>
+Give power of 2 number of slabs, this is used to reduce lock contention
+in the dnscrypt nonce cache. Close to the number of cpus is
+a fairly good setting.
.SS "EDNS Client Subnet Module Options"
.LP
The ECS module must be configured in the \fBmodule\-config:\fR "subnetcache
@@ -1487,7 +1520,7 @@ specialized cache. If the authority indicated no support, the response is
stored in the regular cache.
.LP
Additionally, when a client includes the option in its queries, Unbound will
-forward the option to the authority if prensent in the whitelist, or
+forward the option to the authority if present in the whitelist, or
\fBclient\-subnet\-always\-forward\fR is set to yes. In this case the lookup in
the regular cache is skipped.
.LP