UNBOUND-CONTROL(8)

📦

version 15.1 · 2 versions

15.1 · freebsd 15.1 (latest)
14.5 · freebsd 14.5

🌸 NAME 🌸

okay so bestie, this is the page for local-unbound-control — the Local-unbound 1.25.1 remote server control utility. that's it, that's the vibe. it's the little remote control for your DNS server 💅

✨ SYNOPSIS ✨

unbound-control [-hq] [-c cfgfile] [-s server] command

💖 DESCRIPTION 💖

unbound-control does remote administration on the local-unbound(8) DNS server. like, you're not even in the same room and it still listens to you. iconic. 👑

so what happens: it reads the config file, contacts the Local-unbound server over TLS, sends the command, and shows you the result. that's the whole loop. 🦋

here are the options you can pass, bestie:

-h — shows the version and the commandline option help. the "what do i even type" button 🫶
-c <cfgfile> — the config file to read settings from. if you don't give one, the default /var/unbound/unbound.conf gets used.
-s <server[@port]> — IPv4 or IPv6 address of the server to contact. if you don't give one, the address comes from the config file. ✨
-q — quiet mode. if you pass this, it prints nothing when everything worked ok. silence = slay 💀

🎀 COMMANDS 🎀

there are a bunch of commands the server actually understands. let's go through them, no skipping, i promise 🫡

start — starts the server. literally just execs local-unbound(8). the unbound executable is searched for in the PATH set in the environment, and it's started with the config file you specified using -c, or the default config file. go go go 🏃‍♀️
stop — stops the server. the server daemon exits. bye bestie 😭
reload — reloads the server. this flushes the cache and reads the config file fresh. clean slate energy ✨
reload_keep_cache — reloads the server but tries to keep the RRset and message cache if the (re)configuration allows for it. and what does that mean? the cache sizes and the number of threads must not change between reloads. no cap.
fast_reload [+dpv] — reloads the server but keeps downtime to a minimum so user queries keep seeing service. this needs the code compiled with threads. the config gets loaded in a thread and prepared, then it briefly pauses the existing server and updates config options. the intent is that the pause doesn't impact the service of user queries. the cache is kept. also user queries that are being worked on are kept and continue — but with the new config options. 🧚

NOTE: this command is experimental at this time. you've been warned, bestie 🙈

the amount of temporal memory needed during a fast_reload is twice the amount needed for configuration. why? because Local-unbound temporarily needs to store both the current configuration values and the new ones while trying to fast reload. zones loaded from disk (authority zones and RPZ zones) are included in those 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. iter-scrub-promiscuous. tls-service-key. tls-service-pem. yes i listed every single one, don't test me 💅

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. hard no 🚫

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's more verbose, which includes the amount of memory that was allocated temporarily to perform the reload — and 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's possible for threads to see an inconsistent state, with some options from the old config and some options from the new config. like, 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're 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. that's the whole list, i counted 🍓

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 users keep getting answers for those queries that are currently being processed. the drop makes it so that queries during the lifetime 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. iykyk ✨

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's possible to flush the requestlist with +d. 🌈

verbosity number — changes the verbosity value for logging. same values as the verbosity: keyword in unbound.conf(5). this new setting lasts until the server is issued a reload (taken from the config file again), or the next verbosity control command. 🔥
log_reopen — reopens the logfile: closes it and opens it. useful for logrotation, to make the daemon release the file it's logging to. if you're using syslog it will attempt to close and open the syslog — which may not work if chrooted. ⚠️
stats — prints statistics. resets the internal counters to zero, and this can be controlled using the statistics-cumulative: config statement. statistics are printed with one [name]: [value] per line. 📊
stats_noreset — peeks at statistics. prints them like the stats command does, but does not reset the internal counters to zero. just looking 👀
status — displays server status. exit code 3 if not running (the connection to the port is refused), 1 on error, 0 if running. simple as that 💅
local_zone name type — adds a new local zone with name and type. like the local-zone config statement. if the zone already exists, the type is changed to the given argument. 🎀
local_zone_remove name — removes the local zone with the given name. removes all local data inside it. if the zone doesn't exist, the command still succeeds. no drama 🌸
local_data RR data... — adds new local data: the given resource record. like the local-data: keyword, except for when no covering zone exists. in that case this remote control command creates a transparent zone with the same name as this record. ✨
local_data_remove name — removes all RR data from the 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's still data in domain names below the removed name), NOERROR nodata answers are the result for that name. 😭
local_zones — adds local zones read from stdin of local-unbound-control. input is read per line, with name space type on a line. for bulk additions. 🦋
local_zones_remove — removes local zones read from stdin of local-unbound-control. input is one name per line. for bulk removals. 🧹
local_datas — adds local data RRs read from stdin of local-unbound-control. input is one RR per line. for bulk additions. 📥
local_datas_remove — removes local data RRs read from stdin of local-unbound-control. input is one name per line. for bulk removals. 🗑️
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. not supported in remote Unbounds in multi-process operation. 🚫

`load_cache` 🧚

Okay so this one slurps the contents of the cache in from stdin, using the exact same format that dump_cache spits out. ⚠️ Big warning though: loading the cache with old or straight-up wrong data can absolutely result in old or wrong data getting handed back to clients — like, garbage in, garbage out, bestie. This whole "load data into the cache this way" thing exists purely to help with debugging. Also, it's not supported in remote Unbounds in multi-process operation.

`cache_lookup [+t] names` 🔍

Prints the RRsets and messages that are chilling in the cache to stdout. For every name you list, it prints the content at or under that name. You can pass several names separated by spaces and each one gets printed. If subnetcache is enabled, it also prints matching entries from the subnet cache. ✨

The +t option allows tld and root names — so with it you can use names like 'com' and '.', but fair warning, it takes a lot of effort to look those up in the cache. 😮‍💨

`lookup name` 🕵️‍♀️

Prints to stdout the name servers that would be used to look up the name you specified. Just a peek, no actual resolving drama.

`flush [+c] name` 🗑️

Removes the name from the cache. It removes the types A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV, NAPTR, SVCB and HTTPS — because that's fast to do, periodt. Other record types can be removed using flush_type or flush_zone.