| UNBOUND-CONTROL(8) | Unbound | UNBOUND-CONTROL(8) |
unbound-control - Unbound 1.24.0 remote server control utility.
unbound-control [-hq] [-c cfgfile] [-s server] command
unbound-control performs remote administration on the unbound(8) DNS server. It reads the configuration file, contacts the Unbound server over TLS sends the command and displays the result.
The available options are:
There are several commands that the server understands.
NOTE:
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.
Options that can be changed are for forwards, stubs, views, authority zones, RPZ zones and local zones.
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.
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.
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.
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.
The options dnstap-send-identity, dnstap-send-version, dnstap-identity, and dnstap-version can be loaded when +p is not used.
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.
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.
With the nopause option (+p), 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.
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.
When there are changes to the config tags, from the define-tag 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.
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.
The +t option allows tld and root names. With it names like 'com' and '.' can be used, but it takes a lot of effort to look up in the cache.
The +c option removes the items also from the cachedb cache. If cachedb is in use.
The +c option removes the items also from the cachedb cache. If cachedb is in use.
The +c option removes the items also from the cachedb cache. If cachedb is in use.
The +c option removes the items also from the cachedb cache. If cachedb is in use.
The +c option removes the items also from the cachedb cache. If cachedb is in use.
The values that work are: statistics-interval, statistics-cumulative, do-not-query-localhost, harden-short-bufsize, harden-large-queries, harden-glue, harden-dnssec-stripped, harden-below-nxdomain, harden-referral-path, prefetch, prefetch-key, log-queries, hide-identity, hide-version, identity, version, val-log-level, val-log-squelch, ignore-cd-flag, add-holddown, del-holddown, keep-missing, tcp-upstream, ssl-upstream, max-udp-size, ratelimit, ip-ratelimit, cache-max-ttl, cache-min-ttl, cache-max-negative-ttl.
Without arguments the current list of addresses used to forward all queries to is printed. On startup this is from the forward-zone "." configuration. Afterwards it shows the status. It prints off when no forwarding is used.
If off is passed, forwarding is disabled and the root nameservers are used. This can be used to avoid to avoid buggy or non-DNSSEC supporting nameservers returned from DHCP. But may not work in hotels or hotspots.
If one or more IPv4 or IPv6 addresses are given, those are then used to forward queries to. The addresses must be separated with spaces. With '@port' the port number can be set explicitly (default port is 53 (DNS)).
By default the forwarder information from the config file for the root "." is used. The config file is not changed, so after a reload these changes are gone. Other forward zones from the config file are not affected by this command.
Cookie secrets can be either active or staging. Active cookie secrets are used to create DNS Cookies, but verification of a DNS Cookie succeeds with any of the active or staging cookie secrets. The state of the current cookie secrets can be printed with the print_cookie_secrets command.
When there are no cookie secrets configured yet, the secret is added as active. If there is already an active cookie secret, the secret is added as staging or replacing an existing staging secret.
To "roll" a cookie secret used in an anycast set. The new secret has to be added as staging secret to all nodes in the anycast set. When all nodes can verify DNS Cookies with the new secret, the new secret can be activated with the activate_cookie_secret command. After all nodes have the new secret active for at least one hour, the previous secret can be dropped with the drop_cookie_secret command.
Persistence is accomplished by writing to a file which is configured with the cookie-secret-file option in the server section of the config file. This is disabled by default, "".
The unbound-control program exits with status code 1 on error, 0 on success.
The setup requires a self-signed certificate and private keys for both the server and client. The script unbound-control-setup 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 who can use unbound-control, by default owner and group but not all users. Run the script under the same username as you have configured in unbound.conf or as root, so that the daemon is permitted to read the files, for example with:
sudo -u unbound unbound-control-setup
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 control-enable in unbound.conf.
The stats and stats_noreset commands show a number of statistic counters:
unbound.conf(5), unbound(8).
Unbound developers are mentioned in the CREDITS file in the distribution.
1999-2025, NLnet Labs
| September 18, 2025 | 1.24.0 |