diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Changelog | 265 | ||||
| -rw-r--r-- | doc/README | 2 | ||||
| -rw-r--r-- | doc/example.conf.in | 54 | ||||
| -rw-r--r-- | doc/libunbound.3.in | 4 | ||||
| -rw-r--r-- | doc/unbound-anchor.8.in | 2 | ||||
| -rw-r--r-- | doc/unbound-checkconf.8.in | 2 | ||||
| -rw-r--r-- | doc/unbound-control.8.in | 169 | ||||
| -rw-r--r-- | doc/unbound-host.1.in | 2 | ||||
| -rw-r--r-- | doc/unbound.8.in | 4 | ||||
| -rw-r--r-- | doc/unbound.conf.5.in | 204 |
10 files changed, 638 insertions, 70 deletions
diff --git a/doc/Changelog b/doc/Changelog index fde05db51292..9668a6364cf4 100644 --- a/doc/Changelog +++ b/doc/Changelog @@ -1,9 +1,273 @@ +11 April 2025: Yorgos + - Merge #1265: Fix WSAPoll. + +10 April 2025: Wouter + - Fix for print of connection type in log-replies for dot and doh. + +9 April 2025: Wouter + - Fix to detect if atomic_store links in configure. + - Fix #1264: unbound 1.22.0 leaks memory when doing DoH. + +8 April 2025: Wouter + - Tag for 1.23.0rc1. + - Fix fast_reload to print chroot with config file name. + +7 April 2025: Yorgos + - Merge #902: DNS Error Reporting (RFC 9567). Introduces new + configuration option 'dns-error-reporting' and new statistics for + 'num.dns_error_reports'. + +4 April 2025: Wouter + - Fix mesh_copy_client_info to omit null contents from copy. + - Fix comment name in the rpz nsdname test. + - Fix nettle compile for warnings and ticket keys. + - Fix redis_replica test for unused option defaults and log printout. + - Fix test to speed up common.sh script kill_pid. + - Fix to update common.sh for speed of kill_pid. + +4 April 2025: Yorgos + - Merge #1019: Redis read-only replica support. + Introduces new 'redis-replica-*' options for the Redis cache backend. + +3 April 2025: Wouter + - Fix #1263: Exempt loopback addresses from wait-limit. + - Fix wait-limit-netblock and wait-limit-cookie-netblock config parse + to allow two arguments. + - Fix ub_event and include dnstap and win_svc headers. + - Fix test for stat_values for wait limit defaults for localhost. + - Fix parameter unused warning in net_help.c. + +2 April 2025: Yorgos + - Merge #1262 from markyang92, fix build with + 'gcc-15 -Wbuiltin-declaration-mismatch' error in compat/malloc.c. + - For #1262, ifdef is no longer needed. + +2 April 2025: Wouter + - Fix unbound-control test so it counts the new flush_negative output, + also answers the _ta probe from testns and prints command output + and skip a thread specific test when no threads are available. + - Fix that ub_event has the facility to deal with callbacks for + fast reload, doq, windows-stop and dnstap. + - Fix fast reload test to check if pid exists before acting on it. + +1 April 2025: Wouter + - Fix escape more characters when printing an RR type with an unquoted + string. + - Enable the auth_tls.tdir and auth_tls_failcert.tdir tests. + +31 March 2025: Wouter + - iana portlist update. + - Merge #1042: Fast Reload. The unbound-control fast_reload is added. + It reads changed config in a thread, then only briefly pauses the + service threads, that keep running. DNS service is only interrupted + briefly, less than a second. + - Skip the unit tests for auth_tls.tdir and auth_tls_failcert.tdir. + +27 March 2025: Wouter + - Fix unit test dname log printout typecast. + - Fix for ci test, expat is installed on the osx image. + +26 March 2025: Yorgos + - Fix #1255: Multiple pinnings to vulnerable copies of libexpat. + - For #1255, for ios use an older expat version that does not require + C++11 language features. + - For #1255, for ios disable building tests that require C++11. + - For #1255, for ios try the latest expat version again. + +24 March 2025: Wouter + - Fix #1254: `send failed: Socket is not connected` and + `remote address is 0.0.0.0 port 53`. + +21 March 2025: Wouter + - Fix #1253: Cache entries fail to be removed from Redis cachedb + backend with unbound-control flush* +c. + - Fix for #1253: Fix for redis cachedb backend to expect an integer + reply for the EXPIRE command. + +20 March 2025: Wouter + - Fix print of RR type NSAP-PTR, it is an unquoted string. + +18 March 2025: Wouter + - Fix #1251: WSAPoll first argument cannot be NULL. + - Fix for windows compile create ssl contexts. + +17 March 2025: Wouter + - Fix representation of types GPOS and RESINFO, add rdf type for + unquoted str. + +16 March 2025: Yorgos + - Fix 'unbound-control flush_negative' when reporting removed data; + reported by David 'eqvinox' Lamparter. + +28 February 2025: Wouter + - Merge #1238: Prefer SOURCE_DATE_EPOCH over actual time. + Add --help output description for the SOURCE_DATE_EPOCH variable. + +25 February 2025: Wouter + - Merge #1243: Do not shadow tm on line 236. + +24 February 2025: Yorgos + - Fix hash calculation for cachedb to ignore case. Previously, cached + records there were only relevant for same case queries (if not + already in Unbound's internal cache). + +19 February 2025: Yorgos + - Fix static analysis report about unhandled EOF on error conditions + when reading anchor key files. + - Merge #1241: Fix infra-keep-probing for low infra-cache-max-rtt + values. + +17 February 2025: Yorgos + - Consider reconfigurations when calculating the still_useful_timeout + for servers in the infrastructure cache. + +30 January 2025: Wouter + - Fix #986: Resolving sas.com with dnssec-validation fails though + signed delegations seem to be (mostly) correct. + +29 January 2025: Yorgos + - Make the default value of module-config "validator iterator" + regardless of compilation options. --enable-subnet would implicitly + change the value to enable the subnetcache module by default in the + past. + +24 January 2025: Yorgos + - Merge #1220 from Petr Menšík, Add unbound members group access to + control key. + +21 January 2025: Yorgos + - Use the same interface listening port discovery code for all needed + protocols. + - Port to string only when needed before getaddrinfo(). + - Do not open unencrypted channels next to encrypted ones on the same + port. + - Merge #1224 from Theo Buehler: Do not use DSA API unless USE_DSA is + set. + +21 January 2025: Wouter + - Fix compile of interface check code when dnscrypt or quic is + disabled. + - Fix encoding of RR type ATMA. + - Fix to check length in ATMA string to wire. + - Merge #1229: check before use daemon->shm_info. + +20 January 2025: Yorgos + - Merge #1222: Unique DoT and DoH SSL contexts to allow for different + ALPN. + - Create the quic SSL listening context only when needed. + +15 January 2025: Yorgos + - Merge #1221: Consider auth zones when checking for forwarders. + +14 January 2025: Yorgos + - Add resolver.arpa and service.arpa to the default locally served + zones. + +13 January 2025: Yorgos + - Fix #1213: Misleading error message on default access control causing + refuse. + +10 January 2025: Yorgos + - Merge #1214: Use TCP_NODELAY on TLS sockets to speed up the TLS + handshake. + +31 December 2024: Yorgos + - Merge #1174: Serve expired cache update fixes. Fixes a regression bug + with serve-expired that appeared in 1.22.0 and would not allow the + iterator to update the cache with not-yet-validated entries resulting + in increased outgoing traffic. + +20 December 2024: Yorgos + - For #1207: [FR] Support for RESINFO RRType 261 (RFC9606), add + LDNS_RR_TYPE_RESINFO similar to LDNS_RR_TYPE_TXT. + +13 December 2024: Yorgos + - Merge #1204: ci: set persist-credentials: false for actions/checkout + per zizmor suggestion. + +3 December 2024: Yorgos + - Merge #1189: Fix the dname_str method to cause conversion errors + when the domain name length is 255. + - Merge #1197: dname_str() fixes. + - For #1175, the default value of serve-expired-ttl is set to 86400 + (1 day) as suggested by RFC8767. + - Merge #1198: Fix log-servfail with serve expired and no useful cache + contents. + - Safeguard alias loop while looking in the cache for expired answers. + - Merge #1187: Create the SSL_CTX for QUIC before chroot and privilege + drop. + - Fix typo in log_servfail.tdir test. + +22 November 2024: Yorgos + - Fix #1175: serve-expired does not adhere to secure-by-default + principle. The default value of serve-expired-client-timeout + is set to 1800 as suggested by RFC8767. + - For #1175, update serve-expired tests. + +20 November 2024: Yorgos + - Fix comparison to help static analyzer. + +19 November 2024: Yorgos + - Merge #1169 from Sergey Kacheev, fix: lock-free counters for + auth_zone up/down queries. + +15 November 2024: Wouter + - Fix #1183: the data being used is released in method + nsec3_hash_test_entry. + - Fix for #1183: release nsec3 hashes per test file. + +8 November 2024: Yorgos + - More descriptive text for 'harden-algo-downgrade'. + - Complete fix for max-global-quota to 200. + +6 November 2024: Yorgos + - Increase the default of max-global-quota to 200 from 128 after + operational feedback. Still keeping the possible amplification + factor (CAMP related issues) in the hundreds. + +5 November 2024: Wouter + - Fix for the serve expired DNSSEC information fix, it would not allow + current delegation information be updated in cache. The fix allows + current delegation and validation recursion information to be + updated, but as a consequence no longer has certain expired + information around for later dnssec valid expired responses. + - Fix to log redis timeout error string on failure. + +5 November 2024: Yorgos + - Fix SETEX check during Redis (re)initialization. + +4 November 2024: Wouter + - Fix redis that during a reload it does not fail if the redis + server does not connect or does not respond. It still logs the + errors and if the server is up checks expiration features. + - Merge #1167: Makefile.in: fix occasional parallel build failures + around bison rule. + +1 November 2024: Yorgos + - Merge #1159: Stats for discard-timeout and wait-limit. + - Add test case for #1159. + - Some clean up for stat_values.test. + - Merge #1170 from Melroy van den Berg, Fix chroot manpage + description. + - Merge #1157 from Liang Zhu, Fix heap corruption when calling + ub_ctx_delete in Windows. + +25 October 2024: Yorgos + - Fix #1163: Typos in unbound.conf documentation. + +17 October 2024: Wouter + - Tag for 1.22.0 release. This did not contain the 1154 fix + from 16 oct. The code repository continues with + version 1.22.1 in development. + 16 October 2024: Yorgos - Fix for dnsoverquic and dnstap to use the correct dnstap environment. 16 October 2024: Wouter - Fix for dnstap with dnscrypt and dnstap without dnsoverquic. + - Fix #1154: Tag Incorrectly Applying for Other Interfaces + Using the Same IP. This fix is not for 1.22.0. 14 October 2024: Wouter - Fix to display warning if quic-port is set but dnsoverquic is not @@ -23,6 +287,7 @@ - Fix add reallocarray to alloc stats unit test, and disable override of strdup in unbound-host, and the result of config get option is freed properly. + - Tag for 1.22.0rc1. 9 October 2024: Wouter - Merge #871: DNS over QUIC. This adds `quic-port: 853` and diff --git a/doc/README b/doc/README index 600f0feb2fa7..50d9022dbdca 100644 --- a/doc/README +++ b/doc/README @@ -1,4 +1,4 @@ -README for Unbound 1.22.0 +README for Unbound 1.23.0 Copyright 2007 NLnet Labs http://unbound.net diff --git a/doc/example.conf.in b/doc/example.conf.in index 59090c6bb5d5..ba817288bb62 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.22.0. +# See unbound.conf(5) man page, version 1.23.0. # # this is a comment. @@ -194,7 +194,7 @@ server: # iter-scrub-cname: 11 # Limit on upstream queries for an incoming query and its recursion. - # max-global-quota: 128 + # max-global-quota: 200 # msec for waiting for an unknown server to reply. Increase if you # are behind a slow satellite link, to eg. 1128. @@ -215,6 +215,12 @@ server: # Apart from the default, the wait limit with cookie can be adjusted. # wait-limit-cookie-netblock: 192.0.2.0/24 50000 + # Defaults for loopback, it has no wait limit. + # wait-limit-netblock: 127.0.0.0/8 -1 + # wait-limit-netblock: ::1/128 -1 + # wait-limit-cookie-netblock: 127.0.0.0/8 -1 + # wait-limit-cookie-netblock: ::1/128 -1 + # the amount of memory to use for the RRset cache. # plain value in bytes or you can append k, m or G. default is "4Mb". # rrset-cache-size: 4m @@ -556,8 +562,9 @@ server: # harden-referral-path: no # Harden against algorithm downgrade when multiple algorithms are - # advertised in the DS record. If no, allows the weakest algorithm - # to validate the zone. + # advertised in the DS record. If no, allows any algorithm + # to validate the zone which is the standard behavior for validators. + # Check the manpage for detailed information. # harden-algo-downgrade: no # Harden against unknown records in the authority section and the @@ -730,12 +737,13 @@ server: # disable-edns-do: no # Serve expired responses from cache, with serve-expired-reply-ttl in - # the response, and then attempt to fetch the data afresh. + # the response. By default it first tries to refresh an expired answer. + # Can be configured with serve-expired-client-timeout. # serve-expired: no # # Limit serving of expired responses to configured seconds after # expiration. 0 disables the limit. - # serve-expired-ttl: 0 + # serve-expired-ttl: 86400 # # Set the TTL of expired records to the serve-expired-ttl value after a # failed attempt to retrieve the record from upstream. This makes sure @@ -748,10 +756,9 @@ server: # # Time in milliseconds before replying to the client with expired data. # This essentially enables the serve-stale behavior as specified in - # RFC 8767 that first tries to resolve before - # immediately responding with expired data. 0 disables this behavior. - # A recommended value is 1800. - # serve-expired-client-timeout: 0 + # RFC 8767 that first tries to resolve before immediately responding + # with expired data. 0 disables this behavior. + # serve-expired-client-timeout: 1800 # Return the original TTL as received from the upstream name server rather # than the decrementing TTL as stored in the cache. Enabling this feature @@ -810,6 +817,8 @@ server: # local-zone: "127.in-addr.arpa." nodefault # local-zone: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." nodefault # local-zone: "home.arpa." nodefault + # local-zone: "resolver.arpa." nodefault + # local-zone: "service.arpa." nodefault # local-zone: "onion." nodefault # local-zone: "test." nodefault # local-zone: "invalid." nodefault @@ -1077,6 +1086,11 @@ server: # Note that the ede option above needs to be enabled for this to work. # ede-serve-expired: no + # Enable DNS Error Reporting (RFC9567). + # qname-minimisation is advised to be turned on as well to increase + # privacy on the outgoing reports. + # dns-error-reporting: no + # Specific options for ipsecmod. Unbound needs to be configured with # --enable-ipsecmod for these to take effect. # @@ -1304,9 +1318,9 @@ remote-control: # # redis server's TCP port # redis-server-port: 6379 # # if the server uses a unix socket, set its path, or "" when not used. -# # redis-server-path: "/var/lib/redis/redis-server.sock" +# redis-server-path: "/var/lib/redis/redis-server.sock" # # if the server uses an AUTH password, specify here, or "" when not used. -# # redis-server-password: "" +# redis-server-password: "" # # timeout (in ms) for communication with the redis server # redis-timeout: 100 # # timeout (in ms) for commands, if 0, uses redis-timeout. @@ -1317,6 +1331,22 @@ remote-control: # redis-expire-records: no # # redis logical database to use, 0 is the default database. # redis-logical-db: 0 +# # redis replica server's IP address or host name +# redis-replica-server-host: 127.0.0.1 +# # redis replica server's TCP port +# redis-replica-server-port: 6379 +# # if the replica server uses a unix socket, set its path, or "" when not used. +# redis-replica-server-path: "/var/lib/redis/redis-server.sock" +# # if the replica server uses an AUTH password, specify here, or "" when not used. +# redis-replica-server-password: "" +# # timeout (in ms) for communication with the redis replica server +# redis-replica-timeout: 100 +# # timeout (in ms) for redis replica commands, if 0, uses redis-replica-timeout. +# redis-replica-command-timeout: 0 +# # timeout (in ms) for redis replica connection set up, if 0, uses redis-replica-timeout. +# redis-replica-connect-timeout: 0 +# # redis logical database to use for the replica server, 0 is the default database. +# redis-replica-logical-db: 0 # IPSet # Add specify domain into set via ipset. diff --git a/doc/libunbound.3.in b/doc/libunbound.3.in index bb2a5c26945a..4edc9b3c30af 100644 --- a/doc/libunbound.3.in +++ b/doc/libunbound.3.in @@ -1,4 +1,4 @@ -.TH "libunbound" "3" "Oct 17, 2024" "NLnet Labs" "unbound 1.22.0" +.TH "libunbound" "3" "Apr 24, 2025" "NLnet Labs" "unbound 1.23.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.22.0 functions. +\- Unbound DNS validating resolver 1.23.0 functions. .SH "SYNOPSIS" .B #include <unbound.h> .LP diff --git a/doc/unbound-anchor.8.in b/doc/unbound-anchor.8.in index 66e69cc9c352..c3a8d64cabbe 100644 --- a/doc/unbound-anchor.8.in +++ b/doc/unbound-anchor.8.in @@ -1,4 +1,4 @@ -.TH "unbound-anchor" "8" "Oct 17, 2024" "NLnet Labs" "unbound 1.22.0" +.TH "unbound-anchor" "8" "Apr 24, 2025" "NLnet Labs" "unbound 1.23.0" .\" .\" unbound-anchor.8 -- unbound anchor maintenance utility manual .\" diff --git a/doc/unbound-checkconf.8.in b/doc/unbound-checkconf.8.in index ac657d83089c..73cb0ebcbb5f 100644 --- a/doc/unbound-checkconf.8.in +++ b/doc/unbound-checkconf.8.in @@ -1,4 +1,4 @@ -.TH "unbound-checkconf" "8" "Oct 17, 2024" "NLnet Labs" "unbound 1.22.0" +.TH "unbound-checkconf" "8" "Apr 24, 2025" "NLnet Labs" "unbound 1.23.0" .\" .\" unbound-checkconf.8 -- unbound configuration checker manual .\" diff --git a/doc/unbound-control.8.in b/doc/unbound-control.8.in index 7016e8f12515..449c279d6499 100644 --- a/doc/unbound-control.8.in +++ b/doc/unbound-control.8.in @@ -1,4 +1,4 @@ -.TH "unbound-control" "8" "Oct 17, 2024" "NLnet Labs" "unbound 1.22.0" +.TH "unbound-control" "8" "Apr 24, 2025" "NLnet Labs" "unbound 1.23.0" .\" .\" unbound-control.8 -- unbound remote control manual .\" @@ -60,6 +60,155 @@ Reload the server but try to keep the RRset and message cache if That means the caches sizes and the number of threads must not change between reloads. .TP +.B fast_reload \fR[\fI+dpv\fR] +Reload the server, but keep downtime to a minimum, so that user queries +keep seeing service. This needs the code compiled with threads. The config +is loaded in a thread, and prepared, then it briefly pauses the existing +server and updates config options. The intent is that the pause does not +impact the service of user queries. The cache is kept. Also user queries +worked on are kept and continue, but with the new config options. +.IP +This command is experimental at this time. +.IP +The amount of temporal memory needed during a fast_reload is twice the +amount needed for configuration. +This is because Unbound temporarily needs to store both current configuration +values and new ones while trying to fast_reload. +Zones loaded from disk (authority zones and RPZ zones) are included in such +memory needs. +.IP +Options that can be changed are for +forwards, +stubs, +views, +authority zones, +RPZ zones and +local zones. +.IP +Also +access-control and similar options, +interface-action and similar options and +tcp-connection-limit. +It can reload some +define-tag +changes, more on that below. +Further options include +insecure-lan-zones, +domain-insecure, +trust-anchor-file, +trust-anchor, +trusted-keys-file, +auto-trust-anchor-file, +edns-client-string, +ipset, +log-identity, +infra-cache-numhosts, +msg-cache-size, +rrset-cache-size, +key-cache-size, +ratelimit-size, +neg-cache-size, +num-queries-per-thread, +jostle-timeout, +use-caps-for-id, +unwanted-reply-threshold, +tls-use-sni, +outgoing-tcp-mss, +ip-dscp, +max-reuse-tcp-queries, +tcp-reuse-timeout, +tcp-auth-query-timeout, +delay-close. +.IP +It does not work with +interface and +outgoing-interface changes, +also not with +remote control, +outgoing-port-permit, +outgoing-port-avoid, +msg-buffer-size, +any **\*-slabs** options and +statistics-interval changes. +.IP +For dnstap these options can be changed: +dnstap-log-resolver-query-messages, +dnstap-log-resolver-response-messages, +dnstap-log-client-query-messages, +dnstap-log-client-response-messages, +dnstap-log-forwarder-query-messages and +dnstap-log-forwarder-response-messages. +.IP +It does not work with these options: +dnstap-enable, +dnstap-bidirectional, +dnstap-socket-path, +dnstap-ip, +dnstap-tls, +dnstap-tls-server-name, +dnstap-tls-cert-bundle, +dnstap-tls-client-key-file and +dnstap-tls-client-cert-file. +.IP +The options +dnstap-send-identity, +dnstap-send-version, +dnstap-identity, and +dnstap-version can be loaded +when ``+p`` is not used. +.IP +The '+v' option makes the output verbose which includes the time it took to do +the reload. +With '+vv' it is more verbose which includes the amount of memory that was +allocated temporarily to perform the reload; this amount of memory can be big +if the config has large contents. +In the timing output the 'reload' time is the time during which the server was +paused. +.IP +The '+p' option makes the reload not pause threads, they keep running. +Locks are acquired, but items are updated in sequence, so it is possible +for threads to see an inconsistent state with some options from the old +and some options from the new config, such as cache TTL parameters from the +old config and forwards from the new config. The stubs and forwards are +updated at the same time, so that they are viewed consistently, either old +or new values together. The option makes the reload time take eg. 3 +microseconds instead of 0.3 milliseconds during which the worker threads are +interrupted. So, the interruption is much shorter, at the expense of some +inconsistency. After the reload itself, every worker thread is briefly +contacted to make them release resources, this makes the delete timing +a little longer, and takes up time from the remote control servicing +worker thread. +.IP +With the nopause option, the reload does not work to reload some options, +that fast reload works on without the nopause option: val-bogus-ttl, +val-override-date, val-sig-skew-min, val-sig-skew-max, val-max-restart, +val-nsec3-keysize-iterations, target-fetch-policy, outbound-msg-retry, +max-sent-count, max-query-restarts, do-not-query-address, +do-not-query-localhost, private-address, private-domain, caps-exempt, +nat64-prefix, do-nat64, infra-host-ttl, infra-keep-probing, ratelimit, +ip-ratelimit, ip-ratelimit-cookie, wait-limit-netblock, +wait-limit-cookie-netblock, ratelimit-below-domain, ratelimit-for-domain. +.IP +The '+d' option makes the reload drop queries that the worker threads are +working on. This is like flush_requestlist. Without it the queries are kept +so that users keep getting answers for those queries that are currently +processed. The drop makes it so that queries during the life time of the +query processing see only old, or only new config options. +.IP +When there are changes to the config tags, from the \fBdefine\-tag\fR option, +then the '+d' option is implicitly turned on with a warning printout, and +queries are dropped. +This is to stop references to the old tag information, by the old +queries. If the number of tags is increased in the newly loaded config, by +adding tags at the end, then the implicit '+d' option is not needed. +.IP +For response ip, that is actions associated with IP addresses, and perhaps +intersected with access control tag and action information, those settings +are stored with a query when it comes in based on its source IP address. +The old information is kept with the query until the queries are done. +This is gone when those queries are resolved and finished, or it is possible +to flush the requestlist with '+d'. +.TP .B verbosity \fInumber Change verbosity value for logging. Same values as \fBverbosity\fR keyword in \fIunbound.conf\fR(5). This new setting lasts until the server is issued @@ -422,6 +571,12 @@ number of queries with a client part only DNS Cookie by thread .I threadX.num.queries_cookie_invalid number of queries with an invalid DNS Cookie by thread .TP +.I threadX.num.queries_discard_timeout +number of queries removed due to discard-timeout by thread +.TP +.I threadX.num.queries_wait_limit +number of queries removed due to wait-limit by thread +.TP .I threadX.num.cachehits number of queries that were successfully answered using a cache lookup .TP @@ -441,6 +596,9 @@ request for certificates. .I threadX.num.dnscrypt.malformed number of request that were neither cleartext, not valid dnscrypt messages. .TP +.I threadX.num.dns_error_reports +number of DNS Error Reports generated by thread +.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, @@ -511,6 +669,12 @@ summed over threads. .I total.num.queries_cookie_invalid summed over threads. .TP +.I total.num.queries_discard_timeout +summed over threads. +.TP +.I total.num.queries_wait_limit +summed over threads. +.TP .I total.num.cachehits summed over threads. .TP @@ -529,6 +693,9 @@ summed over threads. .I total.num.dnscrypt.malformed summed over threads. .TP +.I total.num.dns_error_reports +summed over threads. +.TP .I total.num.prefetch summed over threads. .TP diff --git a/doc/unbound-host.1.in b/doc/unbound-host.1.in index 1bd6ff54e4c0..f56a8d4d18ed 100644 --- a/doc/unbound-host.1.in +++ b/doc/unbound-host.1.in @@ -1,4 +1,4 @@ -.TH "unbound\-host" "1" "Oct 17, 2024" "NLnet Labs" "unbound 1.22.0" +.TH "unbound\-host" "1" "Apr 24, 2025" "NLnet Labs" "unbound 1.23.0" .\" .\" unbound-host.1 -- unbound DNS lookup utility .\" diff --git a/doc/unbound.8.in b/doc/unbound.8.in index 51986eb857e1..33c87cde4edf 100644 --- a/doc/unbound.8.in +++ b/doc/unbound.8.in @@ -1,4 +1,4 @@ -.TH "unbound" "8" "Oct 17, 2024" "NLnet Labs" "unbound 1.22.0" +.TH "unbound" "8" "Apr 24, 2025" "NLnet Labs" "unbound 1.23.0" .\" .\" unbound.8 -- unbound manual .\" @@ -9,7 +9,7 @@ .\" .SH "NAME" .B unbound -\- Unbound DNS validating resolver 1.22.0. +\- Unbound DNS validating resolver 1.23.0. .SH "SYNOPSIS" .B unbound .RB [ \-h ] diff --git a/doc/unbound.conf.5.in b/doc/unbound.conf.5.in index 536474349982..4484267dbc79 100644 --- a/doc/unbound.conf.5.in +++ b/doc/unbound.conf.5.in @@ -1,4 +1,4 @@ -.TH "unbound.conf" "5" "Oct 17, 2024" "NLnet Labs" "unbound 1.22.0" +.TH "unbound.conf" "5" "Apr 24, 2025" "NLnet Labs" "unbound 1.23.0" .\" .\" unbound.conf.5 -- unbound.conf manual .\" @@ -326,11 +326,15 @@ The wait limit for the netblock. If not given the wait\-limit value is used. The most specific netblock is used to determine the limit. Useful for overriding the default for a specific, group or individual, server. The value -1 disables wait limits for the netblock. +By default the loopback has a wait limit netblock of -1, it is not limited, +because it is separated from the rest of network for spoofed packets. +The loopback addresses 127.0.0.0/8 and ::1/128 are default at -1. .TP .B wait\-limit\-cookie\-netblock: \fI<netblock> <number> The wait limit for the netblock, when the query has a DNS cookie. If not given, the wait\-limit\-cookie value is used. The value -1 disables wait limits for the netblock. +The loopback addresses 127.0.0.0/8 and ::1/128 are default at -1. .TP .B so\-rcvbuf: \fI<number> If not 0, then set the SO_RCVBUF socket option to get more buffer @@ -716,7 +720,7 @@ and initial ACL (check if the proxy itself is denied/refused by configuration). The proxied address (if any) will then be used as the true client address and will be used where applicable for logging, ACL, DNSTAP, RPZ and IP ratelimiting. PROXYv2 is supported for UDP and TCP/TLS listening interfaces. -There is no support for PROXYv2 on a DoH or DNSCrypt listening interface. +There is no support for PROXYv2 on a DoH, DoQ or DNSCrypt listening interface. Can list multiple, each on a new statement. .TP .B quic\-port: \fI<number> @@ -902,9 +906,8 @@ outside of the chroot directory. 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 -enabled and the default is "@UNBOUND_CHROOT_DIR@". If you give "" no -chroot is performed. +If given a chroot is done to the given directory. The chroot is by default +set to "@UNBOUND_CHROOT_DIR@". If you give "" no chroot is performed. .TP .B username: \fI<name> If given, after binding the port the user privileges are dropped. Default is @@ -1056,11 +1059,11 @@ closer to that of BIND 9, while setting "\-1 \-1 \-1 \-1 \-1" gives behaviour rumoured to be closer to that of BIND 8. .TP .B harden\-short\-bufsize: \fI<yes or no> -Very small EDNS buffer sizes from queries are ignored. Default is on, as +Very small EDNS buffer sizes from queries are ignored. Default is yes, as described in the standard. .TP .B harden\-large\-queries: \fI<yes or no> -Very large queries are ignored. Default is off, since it is legal protocol +Very large queries are ignored. Default is no, since it is legal protocol wise to send these, and could be necessary for operation if TSIG or EDNS payload is very large. .TP @@ -1107,10 +1110,23 @@ to increase the max depth that is checked to. .TP .B harden\-algo\-downgrade: \fI<yes or no> Harden against algorithm downgrade when multiple algorithms are -advertised in the DS record. If no, allows the weakest algorithm to -validate the zone. Default is no. Zone signers must produce zones -that allow this feature to work, but sometimes they do not, and turning -this option off avoids that validation failure. +advertised in the DS record. +This works by first choosing only the strongest DS digest type as per RFC 4509 +(Unbound treats the highest algorithm as the strongest) and then +expecting signatures from all the advertised signing algorithms from the chosen +DS(es) to be present. +If no, allows any one supported algorithm to validate the zone, even if other advertised algorithms are broken. +Default is no. +RFC 6840 mandates that zone signers must produce zones signed with all +advertised algorithms, but sometimes they do not. +RFC 6840 also clarifies that this requirement is not for validators and +validators should accept any single valid path. +It should thus be explicitly noted that this option violates RFC 6840 for +DNSSEC validation and should only be used to perform a signature +completeness test to support troubleshooting. +Using this option may break DNSSEC resolution with non-RFC6840-conforming +signers and/or in multi-signer configurations that don't send all the +advertised signatures. .TP .B harden\-unknown\-additional: \fI<yes or no> Harden against unknown records in the authority section and additional @@ -1131,7 +1147,7 @@ queries. For domains that do not support 0x20 and also fail with fallback because they keep sending different answers, like some load balancers. Can be given multiple times, for different domains. .TP -.B caps\-whitelist: \fI<yes or no> +.B caps\-whitelist: \fI<domain> Alternate syntax for \fBcaps\-exempt\fR. .TP .B qname\-minimisation: \fI<yes or no> @@ -1248,9 +1264,6 @@ Adding \fIrespip\fR to the front will cause RPZ processing to be done on all queries. The default is "\fIvalidator iterator\fR". .IP -When the server is built with -EDNS client subnet support the default is "\fIsubnetcache validator -iterator\fR". Most modules that need to be listed here have to be listed at the beginning of the line. The subnetcachedb module has to be listed just before the iterator. @@ -1390,15 +1403,17 @@ Default is no. .TP .B serve\-expired: \fI<yes or no> 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". +TTL of \fBserve\-expired\-reply\-ttl\fR in the response. +By default the expired answer will be used after a resolution attempt errored +out or is taking more than serve\-expired\-client\-timeout to resolve. +Default is "no". .TP .B serve\-expired\-ttl: \fI<seconds> -Limit serving of expired responses to configured seconds after expiration. 0 -disables the limit. This option only applies when \fBserve\-expired\fR is -enabled. A suggested value per RFC 8767 is between -86400 (1 day) and 259200 (3 days). The default is 0. +Limit serving of expired responses to configured seconds after expiration. +0 disables the limit. +This option only applies when \fBserve\-expired\fR is enabled. +A suggested value per RFC 8767 is between 86400 (1 day) and 259200 (3 days). +The default is 86400. .TP .B serve\-expired\-ttl\-reset: \fI<yes or no> Set the TTL of expired records to the \fBserve\-expired\-ttl\fR value after a @@ -1412,12 +1427,14 @@ TTL value to use when replying with expired data. If use 30 as the value (RFC 8767). The default is 30. .TP .B serve\-expired\-client\-timeout: \fI<msec> -Time in milliseconds before replying to the client with expired data. This -essentially enables the serve-stale behavior as specified in +Time in milliseconds before replying to the client with expired data. +This essentially enables the serve-stale behavior as specified in RFC 8767 that first tries to resolve before immediately -responding with expired data. A recommended value per -RFC 8767 is 1800. Setting this to 0 will disable this -behavior. Default is 0. +responding with expired data. +Setting this to 0 will disable this behavior and instead serve the expired +record immediately from the cache before attempting to refresh it via +resolution. +Default is 1800. .TP .B serve\-original\-ttl: \fI<yes or no> If enabled, Unbound will always return the original TTL as received from @@ -1622,6 +1639,7 @@ given zone. Use \fInodefault\fR if you use exactly that zone, if you want to use a subzone, use \fItransparent\fR. .P The default zones are localhost, reverse 127.0.0.1 and ::1, the home.arpa, +the resolver.arpa, the service.arpa, the onion, test, invalid and the AS112 zones. The AS112 zones are reverse DNS zones for private use and reserved IP addresses for which the servers on the internet cannot provide correct answers. They are configured by @@ -1677,6 +1695,24 @@ local\-data: "home.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" .fi .TP 10 +\h'5'\fIresolver.arpa (RFC 9462)\fR +Default content: +.nf +local\-zone: "resolver.arpa." static +local\-data: "resolver.arpa. 10800 IN NS localhost." +local\-data: "resolver.arpa. 10800 IN + SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" +.fi +.TP 10 +\h'5'\fIservice.arpa (draft-ietf-dnssd-srp-25)\fR +Default content: +.nf +local\-zone: "service.arpa." static +local\-data: "service.arpa. 10800 IN NS localhost." +local\-data: "service.arpa. 10800 IN + SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" +.fi +.TP 10 \h'5'\fIonion (RFC 7686)\fR Default content: .nf @@ -1998,7 +2034,7 @@ Default is 11. Limit on the number of upstream queries sent out for an incoming query and its subqueries from recursion. It is not reset during the resolution. When it is exceeded the query is failed and the lookup process stops. -Default is 128. +Default is 200. .TP 5 .B fast\-server\-permil: \fI<number> Specify how many times out of 1000 to pick from the set of fastest servers. @@ -2053,17 +2089,30 @@ be used. Default is 65001. .TP 5 .B ede: \fI<yes or no> If enabled, Unbound will respond with Extended DNS Error codes (RFC8914). -These EDEs attach informative error messages to a response for various -errors. Default is "no". +These EDEs provide additional information with a response mainly for, but not +limited to, DNS and DNSSEC errors. When the \fBval-log-level\fR option is also set to \fB2\fR, responses with -Extended DNS Errors concerning DNSSEC failures that are not served from cache, -will also contain a descriptive text message about the reason for the failure. +Extended DNS Errors concerning DNSSEC failures will also contain a descriptive +text message about the reason for the failure. +Default is "no". .TP 5 .B ede\-serve\-expired: \fI<yes or no> If enabled, Unbound will attach an Extended DNS Error (RFC8914) Code 3 - Stale -Answer as EDNS0 option to the expired response. Note that this will not attach -the EDE code without setting the global \fBede\fR option to "yes" as well. +Answer as EDNS0 option to the expired response. +The \fBede\fR option needs to be enabled as well for this to work. +Default is "no". +.TP 5 +.B dns\-error\-reporting: \fI<yes or no> +If enabled, Unbound will send DNS Error Reports (RFC9567). +The name servers need to express support by attaching the Report-Channel EDNS0 +option on their replies specifying the reporting agent for the zone. +Any errors encountered during resolution that would result in Unbound +generating an Extended DNS Error (RFC8914) will be reported to the zone's +reporting agent. +The \fBede\fR option does not need to be enabled for this to work. +It is advised that the \fBqname\-minimisation\fR option is also enabled to +increase privacy on the outgoing reports. Default is "no". .SS "Remote Control Options" In the @@ -2476,8 +2525,8 @@ The dynamic library file to load. Repeat this option for every dynlib module instance added to the \fBmodule\-config:\fR option. .SS "DNS64 Module Options" .LP -The dns64 module must be configured in the \fBmodule\-config:\fR "dns64 -validator iterator" directive and be compiled into the daemon to be +The dns64 module must be configured in the \fBmodule\-config:\fR directive +e.g., "dns64 validator iterator" and be compiled into the daemon to be enabled. These settings go in the \fBserver:\fR section. .TP .B dns64\-prefix: \fI<IPv6 prefix>\fR @@ -2577,8 +2626,8 @@ 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 -validator iterator" directive and be compiled into the daemon to be +The ECS module must be configured in the \fBmodule\-config:\fR directive e.g., +"subnetcache validator iterator" and be compiled into the daemon to be enabled. These settings go in the \fBserver:\fR section. .LP If the destination address is allowed in the configuration Unbound will add the @@ -2599,6 +2648,15 @@ configuration file. On top of that, for each query only 100 different subnets are allowed to be stored for each address family. Exceeding that number, older entries will be purged from cache. .LP +Note that due to the nature of how EDNS Client Subnet works, by segregating the +client IP space in order to try and have tailored responses for prefixes of +unknown sizes, resolution and cache response performance are impacted as a +result. +Usage of the subnetcache module should only be enabled in installations that +require such functionality where the resolver and the clients belong to +different networks. +An example of that is an open resolver installation. +.LP This module does not interact with the \fBserve\-expired*\fR and \fBprefetch:\fR options. .TP @@ -2649,8 +2707,8 @@ Specifies the maximum number of subnets ECS answers kept in the ECS radix tree. 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 Unbound by using +The IPsec module must be configured in the \fBmodule\-config:\fR directive +e.g., "ipsecmod validator iterator" and be compiled into Unbound by using \fB\-\-enable\-ipsecmod\fR to be enabled. These settings go in the \fBserver:\fR section. .LP @@ -2715,12 +2773,12 @@ Allow the ipsecmod functionality for the domain so that the module logic will be executed. Can be given multiple times, for different domains. If the option is not specified, all domains are treated as being allowed (default). .TP -.B ipsecmod\-whitelist: \fI<yes or no> +.B ipsecmod\-whitelist: \fI<domain> Alternate syntax for \fBipsecmod\-allow\fR. .SS "Cache DB Module Options" .LP -The Cache DB module must be configured in the \fBmodule\-config:\fR -"validator cachedb iterator" directive and be compiled into the daemon +The Cache DB module must be configured in the \fBmodule\-config:\fR directive +e.g., "validator cachedb iterator" and be compiled into the daemon with \fB\-\-enable\-cachedb\fR. If this module is enabled and configured, the specified backend database works as a second level cache: @@ -2815,12 +2873,12 @@ The TCP port number of the Redis server. This option defaults to 6379. .TP .B redis-server-path: \fI<unix socket path>\fR -The unix socket path to connect to the redis server. Off by default, and it +The unix socket path to connect to the Redis server. Off by default, and it can be set to "" to turn this off. Unix sockets may have better throughput than the IP address option. .TP .B redis-server-password: \fI"<password>"\fR -The Redis AUTH password to use for the redis server. +The Redis AUTH password to use for the Redis server. Only relevant if Redis is configured for client password authorisation. Off by default, and it can be set to "" to turn this off. .TP @@ -2832,12 +2890,14 @@ re-establish a new connection later. This option defaults to 100 milliseconds. .TP .B redis-command-timeout: \fI<msec>\fR -The timeout to use for redis commands, in milliseconds. If 0, it uses the -redis\-timeout value. The default is 0. +The timeout to use for Redis commands, in milliseconds. +If 0, it uses the \fBredis\-timeout\fR value. +The default is 0. .TP .B redis-connect-timeout: \fI<msec>\fR -The timeout to use for redis connection set up, in milliseconds. If 0, it -uses the redis\-timeout value. The default is 0. +The timeout to use for Redis connection set up, in milliseconds. +If 0, it uses the \fBredis\-timeout\fR value. +The default is 0. .TP .B redis-expire-records: \fI<yes or no> If Redis record expiration is enabled. If yes, Unbound sets timeout for Redis @@ -2857,6 +2917,52 @@ for multiple unrelated applications. The default database in Redis is 0 while other logical databases need to be explicitly SELECT'ed upon connecting. This option defaults to 0. +.TP +.B redis-replica-server-host: \fI<server address or name>\fR +The IP (either v6 or v4) address or domain name of the Redis replica server. +In general an IP address should be specified as otherwise Unbound will have to +resolve the name of the server every time it establishes a connection +to the server. +This server is treated as a read-only replica server +(https://redis.io/docs/management/replication/#read-only-replica). +If specified, all Redis read commands will go to this replica server, while +the write commands will go to the \fBredis-server-host\fR. +This option defaults to "" (disabled). +.TP +.B redis-replica-server-port: \fI<port number>\fR +The TCP port number of the Redis replica server. +This option defaults to 6379. +.TP +.B redis-replica-server-path: \fI<unix socket path>\fR +The unix socket path to connect to the Redis server. Off by default, and it +can be set to "" to turn this off. Unix sockets may have better throughput +than the IP address option. +.TP +.B redis-replica-server-password: \fI"<password>"\fR +The Redis AUTH password to use for the Redis replica server. +Only relevant if Redis is configured for client password authorisation. +Off by default, and it can be set to "" to turn this off. +.TP +.B redis-replica-timeout: \fI<msec>\fR +The period until when Unbound waits for a response from the Redis replica sever. +If this timeout expires Unbound closes the connection, treats it as +if the Redis replica server does not have the requested data, and will try to +re-establish a new connection later. +This option defaults to 100 milliseconds. +.TP +.B redis-replica-command-timeout: \fI<msec>\fR +The timeout to use for Redis replica commands, in milliseconds. +If 0, it uses the \fBredis\-replica\-timeout\fR value. +The default is 0. +.TP +.B redis-replica-connect-timeout: \fI<msec>\fR +The timeout to use for Redis replica connection set up, in milliseconds. +If 0, it uses the \fBredis\-replica\-timeout\fR value. +The default is 0. +.TP +.B redis-replica-logical-db: \fI<logical database index> +Same as \fBredis-logical-db\fR but for the Redis replica server. +This option defaults to 0. .SS DNSTAP Logging Options DNSTAP support, when compiled in by using \fB\-\-enable\-dnstap\fR, is enabled in the \fBdnstap:\fR section. |