diff options
| author | Cy Schubert <cy@FreeBSD.org> | 2022-02-17 22:47:14 +0000 |
|---|---|---|
| committer | Cy Schubert <cy@FreeBSD.org> | 2022-02-17 22:47:14 +0000 |
| commit | 3574dc0bd83e731bba79edc130c0569bf05f7af5 (patch) | |
| tree | 0815a1fbcd844efe87c2536cb869f173cfdee16c /doc | |
| parent | 9b87431a326169e72d5ca55670cb3c95205aa350 (diff) | |
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Changelog | 133 | ||||
| -rw-r--r-- | doc/README | 2 | ||||
| -rw-r--r-- | doc/example.conf.in | 63 | ||||
| -rw-r--r-- | doc/libunbound.3.in | 4 | ||||
| -rw-r--r-- | doc/unbound-anchor.8.in | 8 | ||||
| -rw-r--r-- | doc/unbound-checkconf.8.in | 18 | ||||
| -rw-r--r-- | doc/unbound-control.8.in | 80 | ||||
| -rw-r--r-- | doc/unbound-host.1.in | 16 | ||||
| -rw-r--r-- | doc/unbound.8.in | 8 | ||||
| -rw-r--r-- | doc/unbound.conf.5.in | 242 |
10 files changed, 384 insertions, 190 deletions
diff --git a/doc/Changelog b/doc/Changelog index 8aec7694f42d..8af7d3f888ad 100644 --- a/doc/Changelog +++ b/doc/Changelog @@ -1,5 +1,138 @@ +3 February 2022: Wouter + - Fix for #611: Integer overflow in sldns_wire2str_pkt_scan. + +2 February 2022: George + - Merge PR #532 from Shchelk: Fix: buffer overflow bug. + - Merge PR #616: Update ratelimit logic. It also introduces + ratelimit-backoff and ip-ratelimit-backoff configuration options. + - Change aggressive-nsec default to yes. + - Merge PR #617: Update stub/forward-host notation to accept port and + tls-auth-name. + - Update stream_ssl.tdir test to also use the new forward-host + notation. + +2 February 2022: Wouter + - Update version number in repo to 1.15.0 for upcoming release, + since it changes the aggressive-nsec default and the ratelimit change. + - Fix header comment for doxygen for authextstrtoaddr. + - please clang analyzer for loop in test code. + - Fix docker splint test to use more portable uname. + - Update contrib/aaaa-filter-iterator.patch with diff for current + software version. + +1 February 2022: George + - Merge PR #603 from fobser: Use OpenSSL 1.1 API to access DSA and RSA + internals. + +31 January 2022: George + - Fix review comment for use-after-free when failing to send UDP out. + +31 January 2022: Wouter + - iana portlist update. + +29 January 2022: George + - Fix tls-* and ssl-* documented alternate syntax to also be available + through remote-control and unbound-checkconf. + - Better cleanup on failed DoT/DoH listening socket creation. + +26 January 2022: George + - Fix #599: [FR] RFC 9156 (obsoletes RFC 7816), by noting the new RFC + document. + +26 January 2022: Wouter + - Test for NSID in SERVFAIL response due to DNSSEC bogus. + +25 January 2022: George + - Fix #588: Unbound 1.13.2 crashes due to p->pc is NULL in + serviced_udp_callback. + - Merge PR #612: TCP race condition. + +25 January 2022: Wouter + - Fix #610: Undefine-shift in sldns_str2wire_hip_buf. + +19 January 2022: George + - For dnstap, do not wakeupnow right there. Instead zero the timer to + force the wakeup callback asap. + +14 January 2022: George + - Merge PR #605: + - Fix EDNS to upstream where the same option could be attached + more than once. + - Add a region to serviced_query for allocations. + +14 January 2022: Wouter + - Add rpz: for-downstream: yesno option, where the RPZ zone is + authoritatively answered for, so the RPZ zone contents can be + checked with DNS queries directed at the RPZ zone. + - For #602: Allow the module-config "subnetcache validator cachedb + iterator". + +11 January 2022: George + - Fix prematurely terminated TCP queries when a reply has the same ID. + +7 January 2022: Wouter + - Merge #600 from pemensik: Change file mode before changing file + owner. + +5 January 2022: Wouter + - Fix for #596: fix that rpz return message is returned and not just + the rcode from the iterator return path. This fixes signal unset RA + after a CNAME. + - Fix unit tests for rpz now that the AA flag returns successfully from + the iterator loop. + - Fix for #596: add unit test for nsdname trigger and signal unset RA. + - Fix for #596: add unit test for nsip trigger and signal unset RA. + - Fix #598: Fix unbound-checkconf fatal error: module conf + 'respip dns64 validator iterator' is not known to work. + - Fix for #596: Fix rpz-signal-nxdomain-ra to work for clientip + triggered operation. + +4 January 2022: Wouter + - Fix #596: unset the RA bit when a query is blocked by an unbound + RPZ nxdomain reply. The option rpz-signal-nxdomain-ra allows to + signal that a domain is externally blocked to clients when it + is blocked with NXDOMAIN by unsetting RA. + - Fix to add test for rpz-signal-nxdomain-ra. + - Fix #596: only unset RA when NXDOMAIN is signalled. + - Fix that RPZ does not set RD flag on replies, it should be copied + from the query. + +22 December 2021: George + - contrib/aaaa-filter-iterator.patch file renewed diff content to + apply cleanly to the current coderepo for the current code version. + +20 December 2021: George + - Fix #591: Unbound-anchor manpage links to non-existent license file. + +13 December 2021: George + - Add missing configure flags for optional features in the + documentation. + - Fix Unbound capitalization in the documentation. + +13 December 2021: Wouter + - Fix to pick up other class local zone information before unlock. + +10 December 2021: George + - Allow local-data for classes other than IN to inherit a configured + local-zone's type if possible, instead of defaulting to type + transparent as per the implicit rule. + +10 December 2021: Wouter + - Add code similar to fix for ldns for tab between strings, for + consistency, the test case was not broken. + +6 December 2021: Wouter + - Merge PR #581 from fobser: Fix -Wmissing-prototypes and -Wshadow + warnings in rpz. + - Fix validator debug output about DS support, print correct algorithm. + +3 December 2021: Wouter + - Fix compile warning for if_nametoindex on windows 64bit. + 1 December 2021: Wouter - configure is set to 1.14.0, and release branch. + This was released as version 1.14.0 on 9 Dec 2021, with the doxygen + fix below included. The main branch continues as 1.14.1. - Fix doc/unbound.doxygen to remove obsolete tag warning. 1 December 2021: George diff --git a/doc/README b/doc/README index 3b8d0cce3170..9d9794d5cfa5 100644 --- a/doc/README +++ b/doc/README @@ -1,4 +1,4 @@ -README for Unbound 1.14.0 +README for Unbound 1.15.0 Copyright 2007 NLnet Labs http://unbound.net diff --git a/doc/example.conf.in b/doc/example.conf.in index d9f4995e41ef..ab9445fc69f1 100644 --- a/doc/example.conf.in +++ b/doc/example.conf.in @@ -1,7 +1,7 @@ # # Example configuration file. # -# See unbound.conf(5) man page, version 1.14.0. +# See unbound.conf(5) man page, version 1.15.0. # # this is a comment. @@ -82,13 +82,13 @@ server: # num-queries-per-thread, or, use as many as the OS will allow you. # outgoing-range: 4096 - # permit unbound to use this port number or port range for + # permit Unbound to use this port number or port range for # making outgoing queries, using an outgoing interface. # outgoing-port-permit: 32768 - # deny unbound the use this of port number or port range for + # deny Unbound the use this of port number or port range for # making outgoing queries, using an outgoing interface. - # Use this to make sure unbound does not grab a UDP port that some + # Use this to make sure Unbound does not grab a UDP port that some # other server on this computer needs. The default is to avoid # IANA-assigned port numbers. # If multiple outgoing-port-permit and outgoing-port-avoid options @@ -254,7 +254,7 @@ server: # use-systemd: no # Detach from the terminal, run in background, "yes" or "no". - # Set the value to "no" when unbound runs as systemd service. + # Set the value to "no" when Unbound runs as systemd service. # do-daemonize: yes # control which clients are allowed to make (recursive) queries @@ -307,7 +307,7 @@ server: # The pid file can be absolute and outside of the chroot, it is # written just prior to performing the chroot and dropping permissions. # - # Additionally, unbound may need to access /dev/urandom (for entropy). + # Additionally, Unbound may need to access /dev/urandom (for entropy). # How to do this is specific to your OS. # # If you give "" no chroot is performed. The path must not end in a /. @@ -442,7 +442,7 @@ server: # Aggressive NSEC uses the DNSSEC NSEC chain to synthesize NXDOMAIN # and other denials, using information from previous NXDOMAINs answers. - # aggressive-nsec: no + # aggressive-nsec: yes # Use 0x20-encoded random bits in the query to foil spoof attempts. # This feature is an experimental implementation of draft dns-0x20. @@ -517,7 +517,7 @@ server: # Use several entries, one per domain name, to track multiple zones. # # If you want to perform DNSSEC validation, run unbound-anchor before - # you start unbound (i.e. in the system boot scripts). + # you start Unbound (i.e. in the system boot scripts). # And then enable the auto-trust-anchor-file config item. # Please note usage of unbound-anchor root anchor is at your own risk # and under the terms of our LICENSE (see that file in the source). @@ -585,7 +585,7 @@ server: # val-permissive-mode: no # Ignore the CD flag in incoming queries and refuse them bogus data. - # Enable it if the only clients of unbound are legacy servers (w2008) + # Enable it if the only clients of Unbound are legacy servers (w2008) # that set CD but cannot validate themselves. # ignore-cd-flag: no @@ -615,7 +615,7 @@ server: # Return the original TTL as received from the upstream name server rather # than the decrementing TTL as stored in the cache. Enabling this feature - # does not impact cache expiry, it only changes the TTL unbound embeds in + # does not impact cache expiry, it only changes the TTL Unbound embeds in # responses to queries. Note that enabling this feature implicitly disables # enforcement of the configured minimum and maximum TTL. # serve-original-ttl: no @@ -709,9 +709,9 @@ server: # Add example.com into ipset # local-zone: "example.com" ipset - # If unbound is running service for the local host then it is useful + # If Unbound is running service for the local host then it is useful # to perform lan-wide lookups to the upstream, and unblock the - # long list of local-zones above. If this unbound is a dns server + # long list of local-zones above. If this Unbound is a dns server # for a network of computers, disabled is better and stops information # leakage of local lan information. # unblock-lan-zones: no @@ -860,6 +860,10 @@ server: # 0 blocks when ratelimited, otherwise let 1/xth traffic through # ratelimit-factor: 10 + # Aggressive rate limit when the limit is reached and until demand has + # decreased in a 2 second rate window. + # ratelimit-backoff: no + # override the ratelimit for a specific domain name. # give this setting multiple times to have multiple overrides. # ratelimit-for-domain: example.com 1000 @@ -880,6 +884,10 @@ server: # 0 blocks when ip is ratelimited, otherwise let 1/xth traffic through # ip-ratelimit-factor: 10 + # Aggressive rate limit when the limit is reached and until demand has + # decreased in a 2 second rate window. + # ip-ratelimit-backoff: no + # Limit the number of connections simultaneous from a netblock # tcp-connection-limit: 192.0.2.0/24 12 @@ -889,7 +897,7 @@ server: # the number of servers that will be used in the fast server selection. # fast-server-num: 3 - # Specific options for ipsecmod. unbound needs to be configured with + # Specific options for ipsecmod. Unbound needs to be configured with # --enable-ipsecmod for these to take effect. # # Enable or disable ipsecmod (it still needs to be defined in @@ -901,7 +909,7 @@ server: # listed in module-config (above). # ipsecmod-hook: "./my_executable" # - # When enabled unbound will reply with SERVFAIL if the return value of + # When enabled Unbound will reply with SERVFAIL if the return value of # the ipsecmod-hook is not 0. # ipsecmod-strict: no # @@ -966,10 +974,10 @@ remote-control: # For local sockets this option is ignored, and TLS is not used. # control-use-cert: "yes" - # unbound server key file. + # Unbound server key file. # server-key-file: "@UNBOUND_RUN_DIR@/unbound_server.key" - # unbound server certificate file. + # Unbound server certificate file. # server-cert-file: "@UNBOUND_RUN_DIR@/unbound_server.pem" # unbound-control key file. @@ -1072,8 +1080,9 @@ remote-control: # local-zone: "example.com" refuse # DNSCrypt +# To enable, use --enable-dnscrypt to configure before compiling. # Caveats: -# 1. the keys/certs cannot be produced by unbound. You can use dnscrypt-wrapper +# 1. the keys/certs cannot be produced by Unbound. You can use dnscrypt-wrapper # for this: https://github.com/cofyc/dnscrypt-wrapper/blob/master/README.md#usage # 2. dnscrypt channel attaches to an interface. you MUST set interfaces to # listen on `dnscrypt-port` with the follo0wing snippet: @@ -1092,7 +1101,9 @@ remote-control: # dnscrypt-provider-cert: /path/unbound-conf/keys2/1.cert # CacheDB -# Enable external backend DB as auxiliary cache. Specify the backend name +# External backend DB as auxiliary cache. +# To enable, use --enable-cachedb to configure before compiling. +# Specify the backend name # (default is "testframe", which has no use other than for debugging and # testing) and backend-specific options. The 'cachedb' module must be # included in module-config, just before the iterator module. @@ -1102,6 +1113,7 @@ remote-control: # secret-seed: "default" # # # For "redis" backend: +# # (to enable, use --with-libhiredis to configure before compiling) # # redis server's IP address or host name # redis-server-host: 127.0.0.1 # # redis server's TCP port @@ -1113,7 +1125,9 @@ remote-control: # IPSet # Add specify domain into set via ipset. -# Note: To enable ipset unbound needs to run as root user. +# To enable: +# o use --enable-ipset to configure before compiling; +# o Unbound then needs to run as root user. # ipset: # # set name for ip v4 addresses # name-v4: "list-v4" @@ -1121,9 +1135,10 @@ remote-control: # name-v6: "list-v6" # -# Dnstap logging support, if compiled in. To enable, set the dnstap-enable -# to yes and also some of dnstap-log-..-messages to yes. And select an -# upstream log destination, by socket path, TCP or TLS destination. +# Dnstap logging support, if compiled in by using --enable-dnstap to configure. +# To enable, set the dnstap-enable to yes and also some of +# dnstap-log-..-messages to yes. And select an upstream log destination, by +# socket path, TCP or TLS destination. # dnstap: # dnstap-enable: no # # if set to yes frame streams will be used in bidirectional mode @@ -1136,7 +1151,7 @@ remote-control: # dnstap-tls: yes # # name for authenticating the upstream server. or "" disabled. # dnstap-tls-server-name: "" -# # if "", it uses the cert bundle from the main unbound config. +# # if "", it uses the cert bundle from the main Unbound config. # dnstap-tls-cert-bundle: "" # # key file for client authentication, or "" disabled. # dnstap-tls-client-key-file: "" @@ -1172,4 +1187,6 @@ remote-control: # rpz-cname-override: www.example.org # rpz-log: yes # rpz-log-name: "example policy" +# rpz-signal-nxdomain-ra: no +# for-downstream: no # tags: "example" diff --git a/doc/libunbound.3.in b/doc/libunbound.3.in index 6c5217aa04c4..7df4f59d7831 100644 --- a/doc/libunbound.3.in +++ b/doc/libunbound.3.in @@ -1,4 +1,4 @@ -.TH "libunbound" "3" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" +.TH "libunbound" "3" "Feb 10, 2022" "NLnet Labs" "unbound 1.15.0" .\" .\" libunbound.3 -- unbound library functions manual .\" @@ -44,7 +44,7 @@ .B ub_ctx_zone_remove, .B ub_ctx_data_add, .B ub_ctx_data_remove -\- Unbound DNS validating resolver 1.14.0 functions. +\- Unbound DNS validating resolver 1.15.0 functions. .SH "SYNOPSIS" .B #include <unbound.h> .LP diff --git a/doc/unbound-anchor.8.in b/doc/unbound-anchor.8.in index ddab3d27f120..268640d8155c 100644 --- a/doc/unbound-anchor.8.in +++ b/doc/unbound-anchor.8.in @@ -1,4 +1,4 @@ -.TH "unbound-anchor" "8" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" +.TH "unbound-anchor" "8" "Feb 10, 2022" "NLnet Labs" "unbound 1.15.0" .\" .\" unbound-anchor.8 -- unbound anchor maintenance utility manual .\" @@ -41,7 +41,7 @@ update certificate files. .P It tests if the root anchor file works, and if not, and an update is possible, attempts to update the root anchor using the root update certificate. -It performs a https fetch of root-anchors.xml and checks the results (RFC7958), +It performs a https fetch of root-anchors.xml and checks the results (RFC7958), if all checks are successful, it updates the root anchor file. Otherwise the root anchor file is unchanged. It performs RFC5011 tracking if the DNSSEC information available via the DNS makes that possible. @@ -159,7 +159,7 @@ Or something more suitable for your operational environment. The root keys and update certificate included in this tool are provided for convenience and under the terms of our license (see the LICENSE file in the source distribution or -http://unbound.nlnetlabs.nl/svn/trunk/LICENSE) and might be stale or +https://github.com/NLnetLabs/unbound/blob/master/LICENSE) and might be stale or not suitable to your purpose. .P By running "unbound\-anchor \-l" the keys and certificate that are @@ -185,5 +185,5 @@ Source for the root key information. .I https://data.iana.org/root\-anchors/root\-anchors.p7s Signature on the root key information. .SH "SEE ALSO" -\fIunbound.conf\fR(5), +\fIunbound.conf\fR(5), \fIunbound\fR(8). diff --git a/doc/unbound-checkconf.8.in b/doc/unbound-checkconf.8.in index 55ebbc070196..ac8782dcde40 100644 --- a/doc/unbound-checkconf.8.in +++ b/doc/unbound-checkconf.8.in @@ -1,4 +1,4 @@ -.TH "unbound-checkconf" "8" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" +.TH "unbound-checkconf" "8" "Feb 10, 2022" "NLnet Labs" "unbound 1.15.0" .\" .\" unbound-checkconf.8 -- unbound configuration checker manual .\" @@ -9,7 +9,7 @@ .\" .SH "NAME" unbound\-checkconf -\- Check unbound configuration file for errors. +\- Check Unbound configuration file for errors. .SH "SYNOPSIS" .B unbound\-checkconf .RB [ \-h ] @@ -21,8 +21,8 @@ unbound\-checkconf .B Unbound\-checkconf checks the configuration file for the \fIunbound\fR(8) -DNS resolver for syntax and other errors. -The config file syntax is described in +DNS resolver for syntax and other errors. +The config file syntax is described in \fIunbound.conf\fR(5). .P The available options are: @@ -34,19 +34,19 @@ Show the version and commandline option help. Print full pathname, with chroot applied to it. Use with the \-o option. .TP .B \-o\fI option -If given, after checking the config file the value of this option is +If given, after checking the config file the value of this option is printed to stdout. For "" (disabled) options an empty line is printed. .TP .I cfgfile -The config file to read with settings for unbound. It is checked. +The config file to read with settings for Unbound. It is checked. If omitted, the config file at the default location is checked. .SH "EXIT CODE" -The unbound\-checkconf program exits with status code 1 on error, +The unbound\-checkconf program exits with status code 1 on error, 0 for a correct config file. .SH "FILES" .TP .I @ub_conf_file@ -unbound configuration file. +Unbound configuration file. .SH "SEE ALSO" -\fIunbound.conf\fR(5), +\fIunbound.conf\fR(5), \fIunbound\fR(8). diff --git a/doc/unbound-control.8.in b/doc/unbound-control.8.in index ab5413c9a0ba..9d0c10e942bd 100644 --- a/doc/unbound-control.8.in +++ b/doc/unbound-control.8.in @@ -1,4 +1,4 @@ -.TH "unbound-control" "8" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" +.TH "unbound-control" "8" "Feb 10, 2022" "NLnet Labs" "unbound 1.15.0" .\" .\" unbound-control.8 -- unbound remote control manual .\" @@ -14,15 +14,15 @@ .SH "SYNOPSIS" .B unbound\-control .RB [ \-hq ] -.RB [ \-c +.RB [ \-c .IR cfgfile ] -.RB [ \-s +.RB [ \-s .IR server ] .IR command .SH "DESCRIPTION" .B Unbound\-control performs remote administration on the \fIunbound\fR(8) DNS server. -It reads the configuration file, contacts the unbound server over SSL +It reads the configuration file, contacts the Unbound server over SSL sends the command and displays the result. .P The available options are: @@ -44,8 +44,8 @@ quiet, if the option is given it does not print anything if it works ok. There are several commands that the server understands. .TP .B start -Start the server. Simply execs \fIunbound\fR(8). The unbound executable -is searched for in the \fBPATH\fR set in the environment. It is started +Start the server. Simply execs \fIunbound\fR(8). The Unbound executable +is searched for in the \fBPATH\fR set in the environment. It is started with the config file specified using \fI\-c\fR or the default config file. .TP .B stop @@ -65,8 +65,8 @@ daemon release the file it is logging to. If you are using syslog it will attempt to close and open the syslog (which may not work if chrooted). .TP .B stats -Print statistics. Resets the internal counters to zero, this can be -controlled using the \fBstatistics\-cumulative\fR config statement. +Print statistics. Resets the internal counters to zero, this can be +controlled using the \fBstatistics\-cumulative\fR config statement. Statistics are printed with one [name]: [value] per line. .TP .B stats_noreset @@ -74,7 +74,7 @@ Peek at statistics. Prints them like the \fBstats\fR command does, but does not reset the internal counters to zero. .TP .B status -Display server status. Exit code 3 if not running (the connection to the +Display server status. Exit code 3 if not running (the connection to the port is refused), 1 on error, 0 if running. .TP .B local_zone \fIname\fR \fItype @@ -88,14 +88,14 @@ it. If the zone does not exist, the command succeeds. .B local_data \fIRR data... Add new local data, the given resource record. Like \fBlocal\-data\fR config statement, except for when no covering zone exists. In that case -this remote control command creates a transparent zone with the same +this remote control command creates a transparent zone with the same name as this record. .TP .B local_data_remove \fIname Remove all RR data from local name. If the name already has no items, nothing happens. Often results in NXDOMAIN for the name (in a static zone), -but if the name has become an empty nonterminal (there is still data in -domain names below the removed name), NOERROR nodata answers are the +but if the name has become an empty nonterminal (there is still data in +domain names below the removed name), NOERROR nodata answers are the result for that name. .TP .B local_zones @@ -125,22 +125,22 @@ in old or wrong data returned to clients. Loading data into the cache in this way is supported in order to aid with debugging. .TP .B lookup \fIname -Print to stdout the name servers that would be used to look up the +Print to stdout the name servers that would be used to look up the name specified. .TP .B flush \fIname Remove the name from the cache. Removes the types A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV and NAPTR. -Because that is fast to do. Other record types can be removed using -.B flush_type -or +Because that is fast to do. Other record types can be removed using +.B flush_type +or .B flush_zone\fR. .TP .B flush_type \fIname\fR \fItype Remove the name, type information from the cache. .TP .B flush_zone \fIname -Remove all information at or below the name from the cache. +Remove all information at or below the name from the cache. The rrsets and key entries are removed so that new lookups will be performed. This needs to walk and inspect the entire cache, and is a slow operation. The entries are set to expired in the implementation of this command (so, @@ -187,7 +187,7 @@ therefore not flushed. The option must end with a ':' and whitespace must be between the option and the value. Some values may not have an effect if set this way, the new values are not written to the config file, not all options are supported. This is different from the set_option call -in libunbound, where all values work because unbound has not been initialized. +in libunbound, where all values work because Unbound has not been initialized. .IP The values that work are: statistics\-interval, statistics\-cumulative, do\-not\-query\-localhost, harden\-short\-bufsize, harden\-large\-queries, @@ -227,36 +227,36 @@ List the local data RRs in use. The resource records are printed. .TP .B insecure_add \fIzone Add a \fBdomain\-insecure\fR for the given zone, like the statement in unbound.conf. -Adds to the running unbound without affecting the cache contents (which may +Adds to the running Unbound without affecting the cache contents (which may still be bogus, use \fBflush_zone\fR to remove it), does not affect the config file. .TP .B insecure_remove \fIzone Removes domain\-insecure for the given zone. .TP .B forward_add \fR[\fI+i\fR] \fIzone addr ... -Add a new forward zone to running unbound. With +i option also adds a +Add a new forward zone to running Unbound. With +i option also adds a \fIdomain\-insecure\fR for the zone (so it can resolve insecurely if you have a DNSSEC root trust anchor configured for other names). The addr can be IP4, IP6 or nameserver names, like \fIforward-zone\fR config in unbound.conf. .TP .B forward_remove \fR[\fI+i\fR] \fIzone -Remove a forward zone from running unbound. The +i also removes a +Remove a forward zone from running Unbound. The +i also removes a \fIdomain\-insecure\fR for the zone. .TP .B stub_add \fR[\fI+ip\fR] \fIzone addr ... -Add a new stub zone to running unbound. With +i option also adds a +Add a new stub zone to running Unbound. With +i option also adds a \fIdomain\-insecure\fR for the zone. With +p the stub zone is set to prime, without it it is set to notprime. The addr can be IP4, IP6 or nameserver names, like the \fIstub-zone\fR config in unbound.conf. .TP .B stub_remove \fR[\fI+i\fR] \fIzone -Remove a stub zone from running unbound. The +i also removes a +Remove a stub zone from running Unbound. The +i also removes a \fIdomain\-insecure\fR for the zone. .TP .B forward \fR[\fIoff\fR | \fIaddr ...\fR ] Setup forwarding mode. Configures if the server should ask other upstream -nameservers, should go to the internet root nameservers itself, or show +nameservers, should go to the internet root nameservers itself, or show the current config. You could pass the nameservers after a DHCP update. .IP Without arguments the current list of addresses used to forward all queries @@ -296,7 +296,7 @@ status, indicating if the zone is expired and current serial number. Reload the auth zone from zonefile. The zonefile is read in overwriting the current contents of the zone in memory. This changes the auth zone contents itself, not the cache contents. Such cache contents exists if -you set unbound to validate with for-upstream yes and that can be cleared +you set Unbound to validate with for-upstream yes and that can be cleared with \fBflush_zone\fR \fIzone\fR. .TP .B auth_zone_transfer \fIzone\fR @@ -336,7 +336,7 @@ Add a list of \fIlocal_data\fR for given view from stdin. Like local_datas. .SH "EXIT CODE" The unbound\-control program exits with status code 1 on error, 0 on success. .SH "SET UP" -The setup requires a self\-signed certificate and private keys for both +The setup requires a self\-signed certificate and private keys for both the server and client. The script \fIunbound\-control\-setup\fR generates these in the default run directory, or with \-d in another directory. If you change the access control permissions on the key files you can decide @@ -350,7 +350,7 @@ If you have not configured a username in unbound.conf, the keys need read permission for the user credentials under which the daemon is started. The script preserves private keys present in the directory. -After running the script as root, turn on \fBcontrol\-enable\fR in +After running the script as root, turn on \fBcontrol\-enable\fR in \fIunbound.conf\fR. .SH "STATISTIC COUNTERS" The \fIstats\fR command shows a number of statistic counters. @@ -417,8 +417,8 @@ Average time it took to answer queries that needed recursive processing. Note th .TP .I threadX.recursion.time.median The median of the time it took to answer queries that needed recursive -processing. The median means that 50% of the user queries were answered in -less than this time. Because of big outliers (usually queries to non +processing. The median means that 50% of the user queries were answered in +less than this time. Because of big outliers (usually queries to non responsive servers), the average can be bigger than the median. This median has been calculated by interpolation from a histogram. .TP @@ -544,32 +544,32 @@ The total number of queries over all threads with query opcode QUERY. Also printed for other opcodes, UPDATE, ... .TP .I num.query.tcp -Number of queries that were made using TCP towards the unbound server. +Number of queries that were made using TCP towards the Unbound server. .TP .I num.query.tcpout -Number of queries that the unbound server made using TCP outgoing towards +Number of queries that the Unbound server made using TCP outgoing towards other servers. .TP .I num.query.tls -Number of queries that were made using TLS towards the unbound server. +Number of queries that were made using TLS towards the Unbound server. These are also counted in num.query.tcp, because TLS uses TCP. .TP .I num.query.tls.resume Number of TLS session resumptions, these are queries over TLS towards -the unbound server where the client negotiated a TLS session resumption key. +the Unbound server where the client negotiated a TLS session resumption key. .TP .I num.query.https -Number of queries that were made using HTTPS towards the unbound server. +Number of queries that were made using HTTPS towards the Unbound server. These are also counted in num.query.tcp and num.query.tls, because HTTPS uses TLS and TCP. .TP .I num.query.ipv6 -Number of queries that were made using IPv6 towards the unbound server. +Number of queries that were made using IPv6 towards the Unbound server. .TP .I num.query.flags.RD The number of queries that had the RD flag set in the header. Also printed for flags QR, AA, TC, RA, Z, AD, CD. -Note that queries with flags QR, AA or TC may have been rejected +Note that queries with flags QR, AA or TC may have been rejected because of that. .TP .I num.query.edns.present @@ -603,7 +603,7 @@ These queries are also included in the num.answer.rcode.NOERROR number. Common for AAAA lookups when an A record exists, and no AAAA. .TP .I num.answer.secure -Number of answers that were secure. The answer validated correctly. +Number of answers that were secure. The answer validated correctly. The AD bit might have been set in some of these answers, where the client signalled (with DO or AD bit in the query) that they were ready to accept the AD bit in the answer. @@ -644,7 +644,7 @@ per delegation point, and their validation status. .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 +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 @@ -689,11 +689,11 @@ disabled, and cname\-override. .SH "FILES" .TP .I @ub_conf_file@ -unbound configuration file. +Unbound configuration file. .TP .I @UNBOUND_RUN_DIR@ directory with private keys (unbound_server.key and unbound_control.key) and self\-signed certificates (unbound_server.pem and unbound_control.pem). .SH "SEE ALSO" -\fIunbound.conf\fR(5), +\fIunbound.conf\fR(5), \fIunbound\fR(8). diff --git a/doc/unbound-host.1.in b/doc/unbound-host.1.in index b7d4d2350074..94c8ca3dd569 100644 --- a/doc/unbound-host.1.in +++ b/doc/unbound-host.1.in @@ -1,4 +1,4 @@ -.TH "unbound\-host" "1" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" +.TH "unbound\-host" "1" "Feb 10, 2022" "NLnet Labs" "unbound 1.15.0" .\" .\" unbound-host.1 -- unbound DNS lookup utility .\" @@ -15,7 +15,7 @@ .RB [ \-C .IR configfile ] .RB [ \-vdhr46D ] -.RB [ \-c +.RB [ \-c .IR class ] .RB [ \-t .IR type ] @@ -28,12 +28,12 @@ .I hostname .SH "DESCRIPTION" .B Unbound\-host -uses the unbound validating resolver to query for the hostname and display -results. With the \fB\-v\fR option it displays validation +uses the Unbound validating resolver to query for the hostname and display +results. With the \fB\-v\fR option it displays validation status: secure, insecure, bogus (security failure). .P By default it reads no configuration file whatsoever. It attempts to reach -the internet root servers. With \fB\-C\fR an unbound config file and with +the internet root servers. With \fB\-C\fR an Unbound config file and with \fB\-r\fR resolv.conf can be read. .P The available options are: @@ -73,7 +73,7 @@ For example \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546 .TP .B \-D Enables DNSSEC validation. Reads the root anchor from the default configured -root anchor at the default location, \fI@UNBOUND_ROOTKEY_FILE@\fR. +root anchor at the default location, \fI@UNBOUND_ROOTKEY_FILE@\fR. .TP .B \-f \fIkeyfile Reads keys from a file. Every line has a DS or DNSKEY record, in the format @@ -110,9 +110,9 @@ $ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325 .P $ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" 192.0.2.153 .SH "EXIT CODE" -The unbound\-host program exits with status code 1 on error, +The unbound\-host program exits with status code 1 on error, 0 on no error. The data may not be available on exit code 0, exit code 1 means the lookup encountered a fatal error. .SH "SEE ALSO" -\fIunbound.conf\fR(5), +\fIunbound.conf\fR(5), \fIunbound\fR(8). diff --git a/doc/unbound.8.in b/doc/unbound.8.in index 11b02aebcb2e..723f23238b8e 100644 --- a/doc/unbound.8.in +++ b/doc/unbound.8.in @@ -1,4 +1,4 @@ -.TH "unbound" "8" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" +.TH "unbound" "8" "Feb 10, 2022" "NLnet Labs" "unbound 1.15.0" .\" .\" unbound.8 -- unbound manual .\" @@ -9,7 +9,7 @@ .\" .SH "NAME" .B unbound -\- Unbound DNS validating resolver 1.14.0. +\- Unbound DNS validating resolver 1.15.0. .SH "SYNOPSIS" .B unbound .RB [ \-h ] @@ -57,7 +57,7 @@ The available options are: Show the version number and commandline option help, and exit. .TP .B \-c\fI cfgfile -Set the config file with settings for unbound to read instead of reading the +Set the config file with settings for Unbound to read instead of reading the file at the default location, @ub_conf_file@. The syntax is described in \fIunbound.conf\fR(5). .TP @@ -70,7 +70,7 @@ or to syslog, but the log messages are printed to stderr all the time. .TP .B \-p Don't use a pidfile. This argument should only be used by supervision -systems which can ensure that only one instance of unbound will run +systems which can ensure that only one instance of Unbound will run concurrently. .TP .B \-v diff --git a/doc/unbound.conf.5.in b/doc/unbound.conf.5.in index 4c144db22ab5..e1cc5c020756 100644 --- a/doc/unbound.conf.5.in +++ b/doc/unbound.conf.5.in @@ -1,4 +1,4 @@ -.TH "unbound.conf" "5" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" +.TH "unbound.conf" "5" "Feb 10, 2022" "NLnet Labs" "unbound 1.15.0" .\" .\" unbound.conf.5 -- unbound.conf manual .\" @@ -104,7 +104,7 @@ requestlist statistics are printed for every interval (but can be 0). This is because the median calculation requires data to be present. .TP .B statistics\-cumulative: \fI<yes or no> -If enabled, statistics are cumulative since starting unbound, without clearing +If enabled, statistics are cumulative since starting Unbound, without clearing the statistics counters after logging the statistics. Default is no. .TP .B extended\-statistics: \fI<yes or no> @@ -136,7 +136,7 @@ Same as interface: (for ease of compatibility with nsd.conf). Listen on all addresses on all (current and future) interfaces, detect the source interface on UDP queries and copy them to replies. This is a lot like ip\-transparent, but this option services all interfaces whilst with -ip\-transparent you can select which (future) interfaces unbound provides +ip\-transparent you can select which (future) interfaces Unbound provides service on. This feature is experimental, and needs support in your OS for particular socket options. Default value is no. .TP @@ -154,7 +154,7 @@ sent via a random outgoing interface to counter spoofing. If an IPv6 netblock is specified instead of an individual IPv6 address, outgoing UDP queries will use a randomised source address taken from the netblock to counter spoofing. Requires the IPv6 netblock to be routed to the -host running unbound, and requires OS support for unprivileged non-local binds +host running Unbound, and requires OS support for unprivileged non-local binds (currently only supported on Linux). Several netblocks may be specified with multiple .B outgoing\-interface: @@ -174,7 +174,7 @@ numbers need extra resources from the operating system. For performance a very large value is best, use libevent to make this possible. .TP .B outgoing\-port\-permit: \fI<port number or range> -Permit unbound to open this port or range of ports for use to send queries. +Permit Unbound to open this port or range of ports for use to send queries. A larger number of permitted outgoing ports increases resilience against spoofing attempts. Make sure these ports are not needed by other daemons. By default only ports above 1024 that have not been assigned by IANA are used. @@ -187,8 +187,8 @@ processing starts with the non IANA allocated ports above 1024 in the set of allowed ports. .TP .B outgoing\-port\-avoid: \fI<port number or range> -Do not permit unbound to open this port or range of ports for use to send -queries. Use this to make sure unbound does not grab a port that another +Do not permit Unbound to open this port or range of ports for use to send +queries. Use this to make sure Unbound does not grab a port that another daemon needs. The port is avoided on all outgoing interfaces, both IP4 and IP6. 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. @@ -289,7 +289,7 @@ 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 servers do not drop packets (see counter in netstat \-su). Default is 0 (use system value). Otherwise, the number of bytes to ask for, try -"4m" on a busy server. The OS caps it at a maximum, on linux unbound +"4m" on a busy server. The OS caps it at a maximum, on linux Unbound needs root permission to bypass the limit, or the admin can use sysctl net.core.rmem_max. On BSD change kern.ipc.maxsockbuf in /etc/sysctl.conf. On OpenBSD change header and recompile kernel. On Solaris ndd \-set @@ -302,7 +302,7 @@ in answer traffic, otherwise 'send: resource temporarily unavailable' can get logged, the buffer overrun is also visible by netstat \-su. Default is 0 (use system value). Specify the number of bytes to ask for, try "4m" on a very busy server. The OS caps it at a maximum, on -linux unbound needs root permission to bypass the limit, or the admin +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 @@ -319,18 +319,18 @@ At extreme load it could be better to turn it off to distribute the queries evenly, reported for Linux systems (4.4.x). .TP .B ip\-transparent: \fI<yes or no> -If yes, then use IP_TRANSPARENT socket option on sockets where unbound +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\-existent 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 +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. The option uses IP_BINDANY on FreeBSD systems and SO_BINDANY on OpenBSD systems. .TP .B ip\-freebind: \fI<yes or no> -If yes, then use IP_FREEBIND socket option on sockets where unbound +If yes, then use IP_FREEBIND socket option on sockets where Unbound is listening to incoming traffic. Default no. Allows you to bind to IP addresses that are nonlocal or do not exist, like when the network interface or IP address is down. Exists only on Linux, where the similar @@ -560,7 +560,7 @@ service. Can list multiple, each on a new statement. .TP .B tls-session-ticket-keys: \fI<file> If not "", lists files with 80 bytes of random contents that are used to -perform TLS session resumption for clients using the unbound server. +perform TLS session resumption for clients using the Unbound server. These files contain the secret key for the TLS session tickets. First key use to encrypt and decrypt TLS session tickets. Other keys use to decrypt only. With this you can roll over to new keys, @@ -642,8 +642,8 @@ Enable or disable systemd socket activation. Default is no. .TP .B do\-daemonize: \fI<yes or no> -Enable or disable whether the unbound server forks into the background as -a daemon. Set the value to \fIno\fR when unbound runs as systemd service. +Enable or disable whether the Unbound server forks into the background as +a daemon. Set the value to \fIno\fR when Unbound runs as systemd service. Default is yes. .TP .B tcp\-connection\-limit: \fI<IP netblock> <limit> @@ -670,7 +670,7 @@ what almost all clients need). Nonrecursive queries are refused. .IP The \fIallow\fR action does allow nonrecursive queries to access the local\-data that is configured. The reason is that this does not involve -the unbound server recursive lookup algorithm, and static data is served +the Unbound server recursive lookup algorithm, and static data is served in the reply. This supports normal operations where nonrecursive queries are made for the authoritative data. For nonrecursive queries any replies from the dynamic cache are refused. @@ -742,7 +742,7 @@ to chroot and dropping permissions. This allows the pidfile to be Unbound is not able to remove the pidfile after termination when it is located outside of the chroot directory. .IP -Additionally, unbound may need to access /dev/urandom (for entropy) +Additionally, Unbound may need to access /dev/urandom (for entropy) from inside the chroot. .IP If given a chroot is done to the given directory. By default chroot is @@ -776,7 +776,7 @@ The logfile is reopened (for append) when the config file is reread, on SIGHUP. .TP .B use\-syslog: \fI<yes or no> -Sets unbound to send log messages to the syslogd, using +Sets Unbound to send log messages to the syslogd, using \fIsyslog\fR(3). The log facility LOG_DAEMON is used, with identity "unbound". The logfile setting is overridden when use\-syslog is turned on. @@ -786,7 +786,7 @@ The default is to log to syslog. If "" is given (default), then the name of the executable, usually "unbound" is used to report to the log. Enter a string to override it with that, which is useful on systems that run more than one instance of -unbound, with different configurations, so that the logs can be easily +Unbound, with different configurations, so that the logs can be easily distinguished against. .TP .B log\-time\-ascii: \fI<yes or no> @@ -874,12 +874,12 @@ with ascii_ prefix and then an ascii string. If enabled trustanchor.unbound queries are refused. .TP .B target\-fetch\-policy: \fI<"list of numbers"> -Set the target fetch policy used by unbound to determine if it should fetch +Set the target fetch policy used by Unbound to determine if it should fetch nameserver target addresses opportunistically. The policy is described per dependency depth. .IP The number of values determines the maximum dependency depth -that unbound will pursue in answering a query. +that Unbound will pursue in answering a query. A value of \-1 means to fetch all targets opportunistically for that dependency depth. A value of 0 means to fetch on demand only. A positive value fetches that many targets opportunistically. @@ -973,7 +973,7 @@ This option only has effect when qname-minimisation is enabled. Default is no. .B aggressive\-nsec: \fI<yes or no> Aggressive NSEC uses the DNSSEC NSEC chain to synthesize NXDOMAIN and other denials, using information from previous NXDOMAINs answers. -Default is no. It helps to reduce the query rate towards targets that get +Default is yes. It helps to reduce the query rate towards targets that get a very high nonexistent name lookup rate. .TP .B private\-address: \fI<IP address or subnet> @@ -1030,7 +1030,7 @@ a little more CPU. Also if the cache is set to 0, it is no use. Default is no. .TP .B deny\-any: \fI<yes or no> If yes, deny queries of type ANY with an empty response. Default is no. -If disabled, unbound responds with a short list of resource records if some +If disabled, Unbound responds with a short list of resource records if some can be found in the cache and makes the upstream type ANY query if there are none. .TP @@ -1090,7 +1090,7 @@ File with trust anchor for one zone, which is tracked with RFC5011 probes. The probes are run several times per month, thus the machine must be online frequently. The initial file can be one with contents as described in \fBtrust\-anchor\-file\fR. The file is written to when the anchor is updated, -so the unbound user must have write permission. Write permission to the file, +so the Unbound user must have write permission. Write permission to the file, but also to the directory it is in (to create a temporary file, which is necessary to deal with filesystem full events), it must also be inside the chroot (if that is used). @@ -1176,7 +1176,7 @@ the verbosity setting. Default is 0, off. At 1, for every user query that fails a line is printed to the logs. This way you can monitor what happens with validation. Use a diagnosis tool, such as dig or drill, to find out why validation is failing for these queries. At 2, not only -the query that failed is printed but also the reason why unbound thought +the query that failed is printed but also the reason why Unbound thought it was wrong and which server sent the faulty data. .TP .B val\-permissive\-mode: \fI<yes or no> @@ -1188,15 +1188,15 @@ is set in replies. Also logging is performed as for full validation. The default value is "no". .TP .B ignore\-cd\-flag: \fI<yes or no> -Instruct unbound to ignore the CD flag from clients and refuse to +Instruct Unbound to ignore the CD flag from clients and refuse to return bogus answers to them. Thus, the CD (Checking Disabled) flag does not disable checking any more. This is useful if legacy (w2008) servers that set the CD flag but cannot validate DNSSEC themselves are -the clients, and then unbound provides them with DNSSEC protection. +the clients, and then Unbound provides them with DNSSEC protection. The default value is "no". .TP .B serve\-expired: \fI<yes or no> -If enabled, unbound attempts to serve old responses from cache with a +If enabled, Unbound attempts to serve old responses from cache with a TTL of \fBserve\-expired\-reply\-ttl\fR in the response without waiting for the actual resolution to finish. The actual resolution answer ends up in the cache later on. Default is "no". @@ -1227,14 +1227,14 @@ RFC 8767 is 1800. Setting this to 0 will disable this behavior. Default is 0. .TP .B serve\-original\-ttl: \fI<yes or no> -If enabled, unbound will always return the original TTL as received from +If enabled, Unbound will always return the original TTL as received from the upstream name server rather than the decrementing TTL as -stored in the cache. This feature may be useful if unbound serves as a -front-end to a hidden authoritative name server. Enabling this feature does -not impact cache expiry, it only changes the TTL unbound embeds in responses to +stored in the cache. This feature may be useful if Unbound serves as a +front-end to a hidden authoritative name server. Enabling this feature does +not impact cache expiry, it only changes the TTL Unbound embeds in responses to queries. Note that enabling this feature implicitly disables enforcement of -the configured minimum and maximum TTL, as it is assumed users who enable this -feature do not want unbound to change the TTL obtained from an upstream server. +the configured minimum and maximum TTL, as it is assumed users who enable this +feature do not want Unbound to change the TTL obtained from an upstream server. Thus, the values set using \fBcache\-min\-ttl\fR and \fBcache\-max\-ttl\fR are ignored. Default is "no". @@ -1295,11 +1295,11 @@ or gigabytes (1024*1024 bytes in a megabyte). .TP .B unblock\-lan\-zones: \fI<yes or no> Default is disabled. If enabled, then for private address space, -the reverse lookups are no longer filtered. This allows unbound when +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 +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. @@ -1403,7 +1403,7 @@ Breaks out of that view and moves towards the global local zones for answer to the query. If the view first is no, it'll resolve normally. If view first is enabled, it'll break perform that step and check the global answers. For when the view has view specific overrides but some zone has to be -answered from global local zone contents. +answered from global local zone contents. .TP 10 \h'5'\fInodefault\fR Used to turn off default contents for AS112 zones. The other types @@ -1647,8 +1647,9 @@ 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. +overloaded with random names, and keeps Unbound from sending traffic to the +nameservers for those zones. Configured forwarders are excluded from +ratelimiting. .TP 5 .B ratelimit\-size: \fI<memory size> Give the size of the data structure in which the current ongoing rates are @@ -1670,6 +1671,15 @@ This can make ordinary queries complete (if repeatedly queried for), and enter the cache, whilst also mitigating the traffic flow by the factor given. .TP 5 +.B ratelimit\-backoff: \fI<yes or no> +If enabled, the ratelimit is treated as a hard failure instead of the default +maximum allowed constant rate. When the limit is reached, traffic is +ratelimited and demand continues to be kept track of for a 2 second rate +window. No traffic is allowed, except for ratelimit\-factor, until demand +decreases below the configured ratelimit for a 2 second rate window. Useful to +set ratelimit to a suspicious rate to aggressively limit unusually high +traffic. Default is off. +.TP 5 .B ratelimit\-for\-domain: \fI<domain> <number qps or 0> 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 @@ -1686,7 +1696,7 @@ to use different settings for a top\-level\-domain and subdomains. A value of 0 will disable ratelimiting for domain names that end in this name. .TP 5 .B ip\-ratelimit: \fI<number or 0> -Enable global ratelimiting of queries accepted per ip address. +Enable global ratelimiting of queries accepted per IP address. 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 completely dropped and will not receive a reply, SERVFAIL or otherwise. @@ -1713,8 +1723,17 @@ This can make ordinary queries complete (if repeatedly queried for), and enter the cache, whilst also mitigating the traffic flow by the factor given. .TP 5 +.B ip\-ratelimit\-backoff: \fI<yes or no> +If enabled, the ratelimit is treated as a hard failure instead of the default +maximum allowed constant rate. When the limit is reached, traffic is +ratelimited and demand continues to be kept track of for a 2 second rate +window. No traffic is allowed, except for ip\-ratelimit\-factor, until demand +decreases below the configured ratelimit for a 2 second rate window. Useful to +set ip\-ratelimit to a suspicious rate to aggressively limit unusually high +traffic. Default is off. +.TP 5 .B outbound\-msg\-retry: \fI<number> -The number of retries unbound will do in case of a non positive response is +The number of retries Unbound will do in case of a non positive response is received. If a forward nameserver is used, this is the number of retries per forward nameserver in case of throwaway response. .TP 5 @@ -1747,7 +1766,7 @@ In the .B remote\-control: clause are the declarations for the remote control facility. If this is enabled, the \fIunbound\-control\fR(8) utility can be used to send -commands to the running unbound server. The server uses these clauses +commands to the running Unbound server. The server uses these clauses to setup TLSv1 security for the connection. The \fIunbound\-control\fR(8) utility also reads the \fBremote\-control\fR section for options. To setup the correct self\-signed certificates use the @@ -1767,7 +1786,7 @@ the server for the change to take effect. .IP If you set it to an absolute path, a local socket is used. The local socket does not use the certificates and keys, so those files need not be present. -To restrict access, unbound sets permissions on the file to the user and +To restrict access, Unbound sets permissions on the file to the user and group that is configured, the access bits are set to allow the group members to access the control socket file. Put users that need to access the socket in the that group. To restrict access further, create a directory to put @@ -1787,12 +1806,12 @@ and the value of this option is ignored. .B server\-key\-file: \fI<private key file> Path to the server private key, by default unbound_server.key. This file is generated by the \fIunbound\-control\-setup\fR utility. -This file is used by the unbound server, but not by \fIunbound\-control\fR. +This file is used by the Unbound server, but not by \fIunbound\-control\fR. .TP 5 .B server\-cert\-file: \fI<certificate file.pem> Path to the server self signed certificate, by default unbound_server.pem. This file is generated by the \fIunbound\-control\-setup\fR utility. -This file is used by the unbound server, and also by \fIunbound\-control\fR. +This file is used by the Unbound server, and also by \fIunbound\-control\fR. .TP 5 .B control\-key\-file: \fI<private key file> Path to the control client private key, by default unbound_control.key. @@ -1810,24 +1829,24 @@ There may be multiple .B stub\-zone: clauses. Each with a name: and zero or more hostnames or IP addresses. For the stub zone this list of nameservers is used. Class IN is assumed. -The servers should be authority servers, not recursors; unbound performs +The servers should be authority servers, not recursors; Unbound performs the recursive processing itself for stub zones. .P The stub zone can be used to configure authoritative data to be used by the resolver that cannot be accessed using the public internet servers. This is useful for company\-local data or private zones. Setup an authoritative server on a different host (or different port). Enter a config -entry for unbound with +entry for Unbound with .B stub\-addr: <ip address of host[@port]>. -The unbound resolver can then access the data, without referring to the +The Unbound resolver can then access the data, without referring to the public internet for it. .P This setup allows DNSSEC signed zones to be served by that authoritative server, in which case a trusted key entry with the public key -can be put in config, so that unbound can validate the data and set the AD +can be put in config, so that Unbound can validate the data and set the AD 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 +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 @@ -1835,20 +1854,26 @@ 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. +(reverse\-) zone bypass Unbound's filtering of RFC1918 zones. .TP .B name: \fI<domain name> Name of the stub zone. This is the full domain name of the zone. .TP .B stub\-host: \fI<domain name> Name of stub zone nameserver. Is itself resolved before it is used. +To use a nondefault port for DNS communication append '@' with the port number. +If tls is enabled, then you can append a '#' and a name, then it'll check the +tls authentication certificates with that name. If you combine the '@' +and '#', the '@' comes first. If only '#' is used the default port is the +configured tls\-port. .TP .B stub\-addr: \fI<IP address> IP address of stub zone nameserver. Can be IP 4 or IP 6. To use a nondefault port for DNS communication append '@' with the port number. -If tls is enabled, then you can append a '#' and a name, then it'll check -the tls authentication certificates with that name. If you combine -the '@' and '#', the '@' comes first. +If tls is enabled, then you can append a '#' and a name, then it'll check the +tls authentication certificates with that name. If you combine the '@' +and '#', the '@' comes first. If only '#' is used the default port is the +configured tls\-port. .TP .B stub\-prime: \fI<yes or no> This option is by default no. If enabled it performs NS set priming, @@ -1884,10 +1909,10 @@ clauses. Each with a \fBname:\fR and zero or more hostnames or IP addresses. For the forward zone this list of nameservers is used to forward the queries to. The servers listed as \fBforward\-host:\fR and \fBforward\-addr:\fR have to handle further recursion for the query. Thus, -those servers are not authority servers, but are (just like unbound is) -recursive servers too; unbound does not perform recursion itself for the +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 +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 @@ -1899,13 +1924,19 @@ Name of the forward zone. This is the full domain name of the zone. .TP .B forward\-host: \fI<domain name> Name of server to forward to. Is itself resolved before it is used. +To use a nondefault port for DNS communication append '@' with the port number. +If tls is enabled, then you can append a '#' and a name, then it'll check the +tls authentication certificates with that name. If you combine the '@' +and '#', the '@' comes first. If only '#' is used the default port is the +configured tls\-port. .TP .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. -If tls is enabled, then you can append a '#' and a name, then it'll check -the tls authentication certificates with that name. If you combine -the '@' and '#', the '@' comes first. +If tls is enabled, then you can append a '#' and a name, then it'll check the +tls authentication certificates with that name. If you combine the '@' +and '#', the '@' comes first. If only '#' is used the default port is the +configured tls\-port. .IP At high verbosity it logs the TLS certificate, with TLS enabled. If you leave out the '#' and auth name from the forward\-addr, any @@ -1913,7 +1944,7 @@ name is accepted. The cert must also match a CA from the tls\-cert\-bundle. .TP .B forward\-first: \fI<yes or no> If a forwarded query is met with a SERVFAIL error, and this option is -enabled, unbound will fall back to normal recursive resolution for this +enabled, Unbound will fall back to normal recursive resolution for this query as if no query forwarding had been specified. The default is "no". .TP .B forward\-tls\-upstream: \fI<yes or no> @@ -1939,7 +1970,7 @@ have a \fBname:\fR. There can be multiple ones, by listing multiple auth\-zone The authority zone with the name closest to the name looked up is used. Authority zones are processed after \fBlocal\-zones\fR and before cache (\fBfor\-downstream:\fR \fIyes\fR), and when used in this manner -make unbound respond like an authority server. Authority zones are also +make Unbound respond like an authority server. Authority zones are also processed after cache, just before going to the network to fetch information for recursion (\fBfor\-upstream:\fR \fIyes\fR), and when used in this manner provide a local copy of an authority server that speeds up @@ -2000,25 +2031,25 @@ file is downloaded when notified. The primaries from primary: statements are allowed notify by default. .TP .B fallback\-enabled: \fI<yes or no> -Default no. If enabled, unbound falls back to querying the internet as +Default no. If enabled, Unbound falls back to querying the internet as a resolver for this zone when lookups fail. For example for DNSSEC validation failures. .TP .B for\-downstream: \fI<yes or no> -Default yes. If enabled, unbound serves authority responses to -downstream clients for this zone. This option makes unbound behave, for +Default yes. If enabled, Unbound serves authority responses to +downstream clients for this zone. This option makes Unbound behave, for the queries with names in this zone, like one of the authority servers for -that zone. Turn it off if you want unbound to provide recursion for the +that zone. Turn it off if you want Unbound to provide recursion for the zone but have a local copy of zone data. If for\-downstream is no and -for\-upstream is yes, then unbound will DNSSEC validate the contents of the +for\-upstream is yes, then Unbound will DNSSEC validate the contents of the zone before serving the zone contents to clients and store validation results in the cache. .TP .B for\-upstream: \fI<yes or no> -Default yes. If enabled, unbound fetches data from this data collection +Default yes. If enabled, Unbound fetches data from this data collection for answering recursion queries. Instead of sending queries over the internet to the authority servers for this zone, it'll fetch the data directly from -the zone data. Turn it on when you want unbound to provide recursion for +the zone data. Turn it on when you want Unbound to provide recursion for downstream clients, and use the zone data as a local copy to speed up lookups. .TP .B zonemd\-check: \fI<yes or no> @@ -2042,14 +2073,14 @@ a ZONEMD is always a failure, also for nonDNSSEC signed zones. .TP .B zonefile: \fI<filename> The filename where the zone is stored. If not given then no zonefile is used. -If the file does not exist or is empty, unbound will attempt to fetch zone +If the file does not exist or is empty, Unbound will attempt to fetch zone data (eg. from the primary servers). .SS "View Options" .LP There may be multiple .B view: clauses. Each with a \fBname:\fR and zero or more \fBlocal\-zone\fR and -\fBlocal\-data\fR elements. Views can also contain view\-first, +\fBlocal\-data\fR elements. Views can also contain view\-first, response\-ip, response\-ip\-data and local\-data\-ptr elements. View can be mapped to requests by specifying the view name in an \fBaccess\-control\-view\fR element. Options from matching @@ -2142,9 +2173,9 @@ underneath the name given. The .B dnscrypt: clause gives the settings of the dnscrypt channel. While those options are -available, they are only meaningful if unbound was compiled with +available, they are only meaningful if Unbound was compiled with \fB\-\-enable\-dnscrypt\fR. -Currently certificate and secret/public keys cannot be generated by unbound. +Currently certificate and secret/public keys cannot be generated by Unbound. You can use dnscrypt-wrapper to generate those: https://github.com/cofyc/\ dnscrypt-wrapper/blob/master/README.md#usage .TP @@ -2263,7 +2294,7 @@ of 0 is always accepted. Default is 0. .TP .B min\-client\-subnet\-ipv4: \fI<number>\fR Specifies the minimum prefix length of the IPv4 source mask we are willing to -accept in queries. Shorter source masks result in REFUSED answers. Source mask +accept in queries. Shorter source masks result in REFUSED answers. Source mask of 0 is always accepted. Default is 0. .TP .B max\-ecs\-tree\-size\-ipv4: \fI<number>\fR @@ -2276,12 +2307,13 @@ This number applies for each qname/qclass/qtype tuple. Defaults to 100. .SS "Opportunistic IPsec Support Module Options" .LP The IPsec module must be configured in the \fBmodule\-config:\fR "ipsecmod -validator iterator" directive and be compiled into the daemon to be -enabled. These settings go in the \fBserver:\fR section. +validator iterator" directive and be compiled into Unbound by using +\fB\-\-enable\-ipsecmod\fR to be enabled. +These settings go in the \fBserver:\fR section. .LP -When unbound receives an A/AAAA query that is not in the cache and finds a +When Unbound receives an A/AAAA query that is not in the cache and finds a valid answer, it will withhold returning the answer and instead will generate -an IPSECKEY subquery for the same domain name. If an answer was found, unbound +an IPSECKEY subquery for the same domain name. If an answer was found, Unbound will call an external hook passing the following arguments: .TP 10 \h'5'\fIQNAME\fR @@ -2310,19 +2342,19 @@ relevant for opportunistic IPsec. .B ipsecmod-enabled: \fI<yes or no>\fR Specifies whether the IPsec module is enabled or not. The IPsec module still needs to be defined in the \fBmodule\-config:\fR directive. This option -facilitates turning on/off the module without restarting/reloading unbound. +facilitates turning on/off the module without restarting/reloading Unbound. Defaults to yes. .TP .B ipsecmod\-hook: \fI<filename>\fR -Specifies the external hook that unbound will call with \fIsystem\fR(3). The +Specifies the external hook that Unbound will call with \fIsystem\fR(3). The file can be specified as an absolute/relative path. The file needs the proper -permissions to be able to be executed by the same user that runs unbound. It +permissions to be able to be executed by the same user that runs Unbound. It must be present when the IPsec module is defined in the \fBmodule\-config:\fR directive. .TP .B ipsecmod-strict: \fI<yes or no>\fR -If enabled unbound requires the external hook to return a success value of 0. -Failing to do so unbound will reply with SERVFAIL. The A/AAAA answer will also +If enabled Unbound requires the external hook to return a success value of 0. +Failing to do so Unbound will reply with SERVFAIL. The A/AAAA answer will also not be cached. Defaults to no. .TP .B ipsecmod\-max-ttl: \fI<seconds>\fR @@ -2330,7 +2362,7 @@ Time to live maximum for A/AAAA cached records after calling the external hook. Defaults to 3600. .TP .B ipsecmod-ignore-bogus: \fI<yes or no>\fR -Specifies the behaviour of unbound when the IPSECKEY answer is bogus. If set +Specifies the behaviour of Unbound when the IPSECKEY answer is bogus. If set to yes, the hook will be called and the A/AAAA answer will be returned to the client. If set to no, the hook will not be called and the answer to the A/AAAA query will be SERVFAIL. Mainly used for testing. Defaults to no. @@ -2357,7 +2389,7 @@ If Unbound cannot even find an answer in the backend, it resolves the query as usual, and stores the answer in the backend. .P This module interacts with the \fBserve\-expired\-*\fR options and will reply -with expired data if unbound is configured for that. Currently the use +with expired data if Unbound is configured for that. Currently the use of \fBserve\-expired\-client\-timeout:\fR and \fBserve\-expired\-reply\-ttl:\fR is not consistent for data originating from the external cache as these will result in a reply with 0 TTL without trying to @@ -2436,16 +2468,17 @@ re-establish a new connection later. This option defaults to 100 milliseconds. .TP .B redis-expire-records: \fI<yes or no> -If Redis record expiration is enabled. If yes, unbound sets timeout for Redis +If Redis record expiration is enabled. If yes, Unbound sets timeout for Redis records so that Redis can evict keys that have expired automatically. If -unbound is configured with \fBserve-expired\fR and \fBserve-expired-ttl\fR is 0, +Unbound is configured with \fBserve-expired\fR and \fBserve-expired-ttl\fR is 0, this option is internally reverted to "no". Redis SETEX support is required for this option (Redis >= 2.0.0). This option defaults to no. .SS DNSTAP Logging Options -DNSTAP support, when compiled in, is enabled in the \fBdnstap:\fR section. +DNSTAP support, when compiled in by using \fB\-\-enable\-dnstap\fR, is enabled +in the \fBdnstap:\fR section. This starts an extra thread (when compiled with threading) that writes -the log information to the destination. If unbound is compiled without +the log information to the destination. If Unbound is compiled without threading it does not spawn a thread, but connects per-process to the destination. .TP @@ -2503,19 +2536,19 @@ Default is "". .TP .B dnstap-log-resolver-query-messages: \fI<yes or no> Enable to log resolver query messages. Default is no. -These are messages from unbound to upstream servers. +These are messages from Unbound to upstream servers. .TP .B dnstap-log-resolver-response-messages: \fI<yes or no> Enable to log resolver response messages. Default is no. -These are replies from upstream servers to unbound. +These are replies from upstream servers to Unbound. .TP .B dnstap-log-client-query-messages: \fI<yes or no> Enable to log client query messages. Default is no. -These are client queries to unbound. +These are client queries to Unbound. .TP .B dnstap-log-client-response-messages: \fI<yes or no> Enable to log client response messages. Default is no. -These are responses from unbound to clients. +These are responses from Unbound to clients. .TP .B dnstap-log-forwarder-query-messages: \fI<yes or no> Enable to log forwarder query messages. Default is no. @@ -2614,7 +2647,7 @@ allowed notify by default. .TP .B zonefile: \fI<filename> The filename where the zone is stored. If not given then no zonefile is used. -If the file does not exist or is empty, unbound will attempt to fetch zone +If the file does not exist or is empty, Unbound will attempt to fetch zone data (eg. from the primary servers). .TP .B rpz\-action\-override: \fI<action> @@ -2631,6 +2664,17 @@ Log all applied RPZ actions for this RPZ zone. Default is no. .B rpz\-log\-name: \fI<name> Specify a string to be part of the log line, for easy referencing. .TP +.B rpz\-signal\-nxdomain\-ra: \fI<yes or no> +Signal when a query is blocked by the RPZ with NXDOMAIN with an unset RA flag. +This allows certain clients, like dnsmasq, to infer that the domain is +externally blocked. Default is no. +.TP +.B for\-downstream: \fI<yes or no> +If enabled the zone is authoritatively answered for and queries for the RPZ +zone information are answered to downstream clients. This is useful for +monitoring scripts, that can then access the SOA information to check if +the rpz information is up to date. Default is no. +.TP .B tags: \fI<list of tags> Limit the policies from this RPZ clause to clients with a matching tag. Tags need to be defined in \fBdefine\-tag\fR and can be assigned to client addresses @@ -2671,7 +2715,7 @@ server: .SH "FILES" .TP .I @UNBOUND_RUN_DIR@ -default unbound working directory. +default Unbound working directory. .TP .I @UNBOUND_CHROOT_DIR@ default @@ -2679,13 +2723,13 @@ default location. .TP .I @ub_conf_file@ -unbound configuration file. +Unbound configuration file. .TP .I @UNBOUND_PIDFILE@ -default unbound pidfile with process ID of the running daemon. +default Unbound pidfile with process ID of the running daemon. .TP .I unbound.log -unbound log file. default is to log to +Unbound log file. default is to log to \fIsyslog\fR(3). .SH "SEE ALSO" \fIunbound\fR(8), |
