diff options
Diffstat (limited to 'contrib/unbound/doc/unbound-control.8')
| -rw-r--r-- | contrib/unbound/doc/unbound-control.8 | 343 |
1 files changed, 313 insertions, 30 deletions
diff --git a/contrib/unbound/doc/unbound-control.8 b/contrib/unbound/doc/unbound-control.8 index 9d0c10e942bd..abc333c42ff9 100644 --- a/contrib/unbound/doc/unbound-control.8 +++ b/contrib/unbound/doc/unbound-control.8 @@ -1,4 +1,4 @@ -.TH "unbound-control" "8" "Feb 10, 2022" "NLnet Labs" "unbound 1.15.0" +.TH "unbound-control" "8" "Jul 16, 2025" "NLnet Labs" "unbound 1.23.1" .\" .\" unbound-control.8 -- unbound remote control manual .\" @@ -32,7 +32,7 @@ Show the version and commandline option help. .TP .B \-c \fIcfgfile The config file to read with settings. If not given the default -config file @ub_conf_file@ is used. +config file /var/unbound/unbound.conf is used. .TP .B \-s \fIserver[@port] IPv4 or IPv6 address of the server to contact. If not given, the @@ -54,6 +54,161 @@ Stop the server. The server daemon exits. .B reload Reload the server. This flushes the cache and reads the config file fresh. .TP +.B reload_keep_cache +Reload the server but try to keep the RRset and message cache if +(re)configuration allows for it. +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 @@ -115,31 +270,38 @@ Remove local data RRs read from stdin of unbound\-control. Input is one name per line. For bulk removals. .TP .B dump_cache -The contents of the cache is printed in a text format to stdout. You can -redirect it to a file to store the cache in a file. +The content of the cache is printed in a text format to stdout. +You can redirect it to a file to store the cache in a file. +Not supported in remote Unbounds in multi-process operation. .TP .B load_cache -The contents of the cache is loaded from stdin. Uses the same format as -dump_cache uses. Loading the cache with old, or wrong data can result -in old or wrong data returned to clients. Loading data into the cache -in this way is supported in order to aid with debugging. +The content of the cache is loaded from stdin. +Uses the same format as dump_cache uses. +Loading the cache with old, or wrong data can result in old or wrong data +returned to clients. +Loading data into the cache in this way is supported in order to aid with +debugging. +Not supported in remote Unbounds in multi-process operation. .TP .B lookup \fIname Print to stdout the name servers that would be used to look up the name specified. .TP -.B flush \fIname +.B flush \fR[\fI+c\fR] \fIname Remove the name from the cache. Removes the types -A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV and NAPTR. +A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV, NAPTR, SVCB and HTTPS. Because that is fast to do. Other record types can be removed using .B flush_type or .B flush_zone\fR. +.IP +The '+c' option removes the items also from the cachedb cache. If +cachedb is in use. .TP -.B flush_type \fIname\fR \fItype +.B flush_type \fR[\fI+c\fR] \fIname\fR \fItype Remove the name, type information from the cache. .TP -.B flush_zone \fIname +.B flush_zone \fR[\fI+c\fR] \fIname 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. @@ -147,10 +309,10 @@ The entries are set to expired in the implementation of this command (so, with serve\-expired enabled, it'll serve that information but schedule a prefetch for new information). .TP -.B flush_bogus +.B flush_bogus \fR[\fI+c\fR] Remove all bogus data from the cache. .TP -.B flush_negative +.B flush_negative \fR[\fI+c\fR] Remove all negative data from the cache. This is nxdomain answers, nodata answers and servfail answers. Also removes bad key entries (which could be due to failed lookups) from the dnssec key cache, and @@ -233,22 +395,24 @@ still be bogus, use \fBflush_zone\fR to remove it), does not affect the config f .B insecure_remove \fIzone Removes domain\-insecure for the given zone. .TP -.B forward_add \fR[\fI+i\fR] \fIzone addr ... +.B forward_add \fR[\fI+it\fR] \fIzone addr ... 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. +The +t option sets it to use tls upstream, like \fIforward\-tls\-upstream\fR: yes. .TP .B forward_remove \fR[\fI+i\fR] \fIzone 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 ... +.B stub_add \fR[\fI+ipt\fR] \fIzone addr ... 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. +The +t option sets it to use tls upstream, like \fIstub\-tls\-upstream\fR: yes. .TP .B stub_remove \fR[\fI+i\fR] \fIzone Remove a stub zone from running Unbound. The +i also removes a @@ -289,20 +453,22 @@ just the ratelimited ips, with their estimated qps. The ratelimited ips are dropped before checking the cache. .TP .B list_auth_zones -List the auth zones that are configured. Printed one per line with a -status, indicating if the zone is expired and current serial number. +List the auth zones that are configured. Printed one per line with a status, +indicating if the zone is expired and current serial number. Configured RPZ +zones are included. .TP .B auth_zone_reload \fIzone\fR -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 -with \fBflush_zone\fR \fIzone\fR. +Reload the auth zone (or RPZ 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 with +\fBflush_zone\fR \fIzone\fR. .TP .B auth_zone_transfer \fIzone\fR -Transfer the auth zone from master. The auth zone probe sequence is started, -where the masters are probed to see if they have an updated zone (with the SOA -serial check). And then the zone is transferred for a newer zone version. +Transfer the auth zone (or RPZ zone) from master. The auth zone probe sequence +is started, where the masters are probed to see if they have an updated zone +(with the SOA serial check). And then the zone is transferred for a newer zone +version. .TP .B rpz_enable \fIzone\fR Enable the RPZ zone if it had previously been disabled. @@ -333,6 +499,41 @@ Remove a list of \fIlocal_data\fR for given view from stdin. Like local_datas_re .TP .B view_local_datas \fIview\fR Add a list of \fIlocal_data\fR for given view from stdin. Like local_datas. +.TP +.B add_cookie_secret <secret> +Add or replace a cookie secret persistently. <secret> needs to be an 128 bit +hex string. +.IP +Cookie secrets can be either \fIactive\fR or \fIstaging\fR. \fIActive\fR cookie +secrets are used to create DNS Cookies, but verification of a DNS Cookie +succeeds with any of the \fIactive\fR or \fIstaging\fR cookie secrets. The +state of the current cookie secrets can be printed with the +\fBprint_cookie_secrets\fR command. +.IP +When there are no cookie secrets configured yet, the <secret> is added as +\fIactive\fR. If there is already an \fIactive\fR cookie secret, the <secret> +is added as \fIstaging\fR or replacing an existing \fIstaging\fR secret. +.IP +To "roll" a cookie secret used in an anycast set. The new secret has to be +added as staging secret to \fBall\fR nodes in the anycast set. When \fBall\fR +nodes can verify DNS Cookies with the new secret, the new secret can be +activated with the \fBactivate_cookie_secret\fR command. After \fBall\fR nodes +have the new secret \fIactive\fR for at least one hour, the previous secret can +be dropped with the \fBdrop_cookie_secret\fR command. +.IP +Persistence is accomplished by writing to a file which if configured with the +\fBcookie\-secret\-file\fR option in the server section of the config file. +This is disabled by default, "". +.TP +.B drop_cookie_secret +Drop the \fIstaging\fR cookie secret. +.TP +.B activate_cookie_secret +Make the current \fIstaging\fR cookie secret \fIactive\fR, and the current +\fIactive\fR cookie secret \fIstaging\fR. +.TP +.B print_cookie_secrets +Show the current configured cookie secrets with their status. .SH "EXIT CODE" The unbound\-control program exits with status code 1 on error, 0 on success. .SH "SET UP" @@ -361,6 +562,21 @@ number of queries received by thread .I threadX.num.queries_ip_ratelimited number of queries rate limited by thread .TP +.I threadX.num.queries_cookie_valid +number of queries with a valid DNS Cookie by thread +.TP +.I threadX.num.queries_cookie_client +number of queries with a client part only DNS Cookie by thread +.TP +.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 @@ -380,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, @@ -390,6 +609,14 @@ as a cache response was sent. .I threadX.num.expired number of replies that served an expired cache entry. .TP +.I threadX.num.queries_timed_out +number of queries that are dropped because they waited in the UDP socket buffer +for too long. +.TP +.I threadX.query.queue_time_us.max +The maximum wait time for packets in the socket buffer, in microseconds. This +is only reported when sock-queue-timeout is enabled. +.TP .I threadX.num.recursivereplies The number of replies sent to queries that needed recursive processing. Could be smaller than threadX.num.cachemiss if due to timeouts no replies were sent for some queries. .TP @@ -430,6 +657,24 @@ buffers are full. .I total.num.queries summed over threads. .TP +.I total.num.queries_ip_ratelimited +summed over threads. +.TP +.I total.num.queries_cookie_valid +summed over threads. +.TP +.I total.num.queries_cookie_client +summed over threads. +.TP +.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 @@ -448,12 +693,21 @@ 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 .I total.num.expired summed over threads. .TP +.I total.num.queries_timed_out +summed over threads. +.TP +.I total.query.queue_time_us.max +the maximum of the thread values. +.TP .I total.num.recursivereplies summed over threads. .TP @@ -519,6 +773,10 @@ queries waiting for request stream completion. Memory in bytes used by the HTTP/2 response buffers. Containing DNS responses waiting to be written back to the clients. .TP +.I mem.quic +Memory in bytes used by QUIC. Containing connection information, stream +information, queries read and responses written back to the clients. +.TP .I histogram.<sec>.<usec>.to.<sec>.<usec> Shows a histogram, summed over all threads. Every element counts the recursive queries whose reply time fit between the lower and upper bound. @@ -550,6 +808,10 @@ Number of queries that were made using TCP towards the Unbound server. Number of queries that the Unbound server made using TCP outgoing towards other servers. .TP +.I num.query.udpout +Number of queries that the Unbound server made using UDP outgoing towards +other servers. +.TP .I num.query.tls Number of queries that were made using TLS towards the Unbound server. These are also counted in num.query.tcp, because TLS uses TCP. @@ -563,6 +825,10 @@ 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.quic +Number of queries that were made using QUIC towards the Unbound server. +These are also counted in num.query.tls, because TLS is used for these queries. +.TP .I num.query.ipv6 Number of queries that were made using IPv6 towards the Unbound server. .TP @@ -585,7 +851,7 @@ ratelimiting. .TP .I num.query.dnscrypt.shared_secret.cachemiss The number of dnscrypt queries that did not find a shared secret in the cache. -The can be use to compute the shared secret hitrate. +This can be used to compute the shared secret hitrate. .TP .I num.query.dnscrypt.replay The number of dnscrypt queries that found a nonce hit in the nonce cache and @@ -641,6 +907,18 @@ timing and protocol support information. The number of items in the key cache. These are DNSSEC keys, one item per delegation point, and their validation status. .TP +.I msg.cache.max_collisions +The maximum number of hash table collisions in the msg cache. This is the +number of hashes that are identical when a new element is inserted in the +hash table. If the value is very large, like hundreds, something is wrong +with the performance of the hash table, hash values are incorrect or malicious. +.TP +.I rrset.cache.max_collisions +The maximum number of hash table collisions in the rrset cache. This is the +number of hashes that are identical when a new element is inserted in the +hash table. If the value is very large, like hundreds, something is wrong +with the performance of the hash table, hash values are incorrect or malicious. +.TP .I dnscrypt_shared_secret.cache.count The number of items in the shared secret cache. These are precomputed shared secrets for a given client public key/server secret key pair. Shared secrets @@ -680,7 +958,12 @@ Number of queries that got an answer that contained EDNS client subnet data. .I num.query.subnet_cache Number of queries answered from the edns client subnet cache. These are counted as cachemiss by the main counters, but hit the client subnet -specific cache, after getting processed by the edns client subnet module. +specific cache after getting processed by the edns client subnet module. +.TP +.I num.query.cachedb +Number of queries answered from the external cache of cachedb. +These are counted as cachemiss by the main counters, but hit the cachedb +external cache after getting processed by the cachedb module. .TP .I num.rpz.action.<rpz_action> Number of queries answered using configured RPZ policy, per RPZ action type. @@ -688,10 +971,10 @@ Possible actions are: nxdomain, nodata, passthru, drop, tcp\-only, local\-data, disabled, and cname\-override. .SH "FILES" .TP -.I @ub_conf_file@ +.I /var/unbound/unbound.conf Unbound configuration file. .TP -.I @UNBOUND_RUN_DIR@ +.I /var/unbound 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" |