1unbound-control(8)               unbound 1.7.3              unbound-control(8)
2
3
4

NAME

6       unbound-control,  unbound-control-setup - Unbound remote server control
7       utility.
8

SYNOPSIS

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

DESCRIPTION

13       Unbound-control performs remote administration on  the  unbound(8)  DNS
14       server.   It  reads the configuration file, contacts the unbound server
15       over SSL sends the command and displays the result.
16
17       The available options are:
18
19       -h     Show the version and commandline option help.
20
21       -c cfgfile
22              The config file to read with settings.  If not given the default
23              config file /etc/unbound/unbound.conf is used.
24
25       -s server[@port]
26              IPv4  or  IPv6  address of the server to contact.  If not given,
27              the address is read from the config file.
28
29       -q     quiet, if the option is given it does not print anything  if  it
30              works ok.
31

COMMANDS

33       There are several commands that the server understands.
34
35       start  Start  the  server.  Simply  execs unbound(8).  The unbound exe‐
36              cutable is searched for in the PATH set in the environment.   It
37              is  started  with  the  config  file  specified  using -c or the
38              default config file.
39
40       stop   Stop the server. The server daemon exits.
41
42       reload Reload the server. This flushes the cache and reads  the  config
43              file fresh.
44
45       verbosity number
46              Change  verbosity  value  for  logging. Same values as verbosity
47              keyword in unbound.conf(5).  This new setting  lasts  until  the
48              server is issued a reload (taken from config file again), or the
49              next verbosity control command.
50
51       log_reopen
52              Reopen the logfile, close and open it.  Useful  for  logrotation
53              to  make  the  daemon release the file it is logging to.  If you
54              are using syslog it will attempt to close and  open  the  syslog
55              (which may not work if chrooted).
56
57       stats  Print statistics. Resets the internal counters to zero, this can
58              be controlled using the statistics-cumulative config  statement.
59              Statistics are printed with one [name]: [value] per line.
60
61       stats_noreset
62              Peek at statistics. Prints them like the stats command does, but
63              does not reset the internal counters to zero.
64
65       status Display server status. Exit code 3 if not running  (the  connec‐
66              tion to the port is refused), 1 on error, 0 if running.
67
68       local_zone name type
69              Add  new  local  zone with name and type. Like local-zone config
70              statement.  If the zone already exists, the type is  changed  to
71              the given argument.
72
73       local_zone_remove name
74              Remove  the  local  zone with the given name.  Removes all local
75              data inside it.  If the zone does not exist,  the  command  suc‐
76              ceeds.
77
78       local_data RR data...
79              Add  new  local data, the given resource record. Like local-data
80              config statement, except for when no covering zone  exists.   In
81              that case this remote control command creates a transparent zone
82              with the same name as this record.  This command is not good  at
83              returning detailed syntax errors.
84
85       local_data_remove name
86              Remove  all RR data from local name.  If the name already has no
87              items, nothing happens.  Often results in NXDOMAIN for the  name
88              (in  a static zone), but if the name has become an empty nonter‐
89              minal (there is still data in domain  names  below  the  removed
90              name), NOERROR nodata answers are the result for that name.
91
92       local_zones
93              Add  local  zones  read  from stdin of unbound-control. Input is
94              read per line, with name space type on a line.  For  bulk  addi‐
95              tions.
96
97       local_zones_remove
98              Remove  local zones read from stdin of unbound-control. Input is
99              one name per line. For bulk removals.
100
101       local_datas
102              Add local data RRs read from stdin of unbound-control. Input  is
103              one RR per line. For bulk additions.
104
105       local_datas_remove
106              Remove  local data RRs read from stdin of unbound-control. Input
107              is one name per line. For bulk removals.
108
109       dump_cache
110              The contents of the cache is printed in a text format to stdout.
111              You can redirect it to a file to store the cache in a file.
112
113       load_cache
114              The  contents  of the cache is loaded from stdin.  Uses the same
115              format as dump_cache uses.  Loading the cache with old, or wrong
116              data can result in old or wrong data returned to clients.  Load‐
117              ing data into the cache in this way is supported in order to aid
118              with debugging.
119
120       lookup name
121              Print  to  stdout the name servers that would be used to look up
122              the name specified.
123
124       flush name
125              Remove the name from the cache. Removes the types A,  AAAA,  NS,
126              SOA, CNAME, DNAME, MX, PTR, SRV and NAPTR.  Because that is fast
127              to do. Other record types can be  removed  using  flush_type  or
128              flush_zone.
129
130       flush_type name type
131              Remove the name, type information from the cache.
132
133       flush_zone name
134              Remove all information at or below the name from the cache.  The
135              rrsets and key entries are removed so that new lookups  will  be
136              performed.  This needs to walk and inspect the entire cache, and
137              is a slow operation.  The entries are  set  to  expired  in  the
138              implementation  of this command (so, with serve-expired enabled,
139              it'll serve that information but schedule  a  prefetch  for  new
140              information).
141
142       flush_bogus
143              Remove all bogus data from the cache.
144
145       flush_negative
146              Remove  all  negative  data  from  the  cache.  This is nxdomain
147              answers, nodata answers and servfail answers.  Also removes  bad
148              key  entries  (which  could  be  due to failed lookups) from the
149              dnssec key cache, and iterator last-resort lookup failures  from
150              the rrset cache.
151
152       flush_stats
153              Reset statistics to zero.
154
155       flush_requestlist
156              Drop  the  queries  that  are  worked  on.  Stops working on the
157              queries that the server is working on now.  The cache  is  unaf‐
158              fected.   No  reply  is  sent for those queries, probably making
159              those users request again later.   Useful  to  make  the  server
160              restart  working  on queries with new settings, such as a higher
161              verbosity level.
162
163       dump_requestlist
164              Show what is worked on.  Prints all queries that the  server  is
165              currently  working  on.   Prints  the  time that users have been
166              waiting.  For internal requests, no time is printed.   And  then
167              prints  out the module status.  This prints the queries from the
168              first thread, and not queries that are being serviced from other
169              threads.
170
171       flush_infra all|IP
172              If  all  then  entire  infra cache is emptied.  If a specific IP
173              address, the entry for that address is removed from  the  cache.
174              It contains EDNS, ping and lameness data.
175
176       dump_infra
177              Show the contents of the infra cache.
178
179       set_option opt: val
180              Set  the  option to the given value without a reload.  The cache
181              is therefore not flushed.  The option must end with  a  ':'  and
182              whitespace  must be between the option and the value.  Some val‐
183              ues may not have an effect if set this way, the new  values  are
184              not  written  to the config file, not all options are supported.
185              This is different from the set_option call in libunbound,  where
186              all values work because unbound has not been initialized.
187
188              The  values that work are: statistics-interval, statistics-cumu‐
189              lative,      do-not-query-localhost,       harden-short-bufsize,
190              harden-large-queries,    harden-glue,    harden-dnssec-stripped,
191              harden-below-nxdomain,      harden-referral-path,      prefetch,
192              prefetch-key,  log-queries,  hide-identity,  hide-version, iden‐
193              tity, version, val-log-level,  val-log-squelch,  ignore-cd-flag,
194              add-holddown,    del-holddown,    keep-missing,    tcp-upstream,
195              ssl-upstream,     max-udp-size,     ratelimit,     ip-ratelimit,
196              cache-max-ttl, cache-min-ttl, cache-max-negative-ttl.
197
198       get_option opt
199              Get  the  value  of  the option.  Give the option name without a
200              trailing ':'.  The value is printed.  If the value is "",  noth‐
201              ing  is printed and the connection closes.  On error 'error ...'
202              is printed (it gives a syntax error  on  unknown  option).   For
203              some  options  a  list  of values, one on each line, is printed.
204              The options are shown from the  config  file  as  modified  with
205              set_option.   For  some  options an override may have been taken
206              that does not show up with this command, not results  from  e.g.
207              the  verbosity  and  forward  control commands.  Not all options
208              work,  see  list_stubs,  list_forwards,   list_local_zones   and
209              list_local_data for those.
210
211       list_stubs
212              List the stub zones in use.  These are printed one by one to the
213              output.  This includes the root hints in use.
214
215       list_forwards
216              List the forward zones in use.  These are printed zone  by  zone
217              to the output.
218
219       list_insecure
220              List the zones with domain-insecure.
221
222       list_local_zones
223              List  the  local  zones  in use.  These are printed one per line
224              with zone type.
225
226       list_local_data
227              List the local data  RRs  in  use.   The  resource  records  are
228              printed.
229
230       insecure_add zone
231              Add  a domain-insecure for the given zone, like the statement in
232              unbound.conf.  Adds to the running unbound without affecting the
233              cache  contents  (which  may  still  be bogus, use flush_zone to
234              remove it), does not affect the config file.
235
236       insecure_remove zone
237              Removes domain-insecure for the given zone.
238
239       forward_add [+i] zone addr ...
240              Add a new forward zone to running unbound.  With +i option  also
241              adds  a  domain-insecure  for  the zone (so it can resolve inse‐
242              curely if you have a DNSSEC root  trust  anchor  configured  for
243              other  names).   The  addr  can be IP4, IP6 or nameserver names,
244              like forward-zone config in unbound.conf.
245
246       forward_remove [+i] zone
247              Remove a forward zone from running unbound.  The +i also removes
248              a domain-insecure for the zone.
249
250       stub_add [+ip] zone addr ...
251              Add  a  new  stub  zone to running unbound.  With +i option also
252              adds a domain-insecure for the zone.  With +p the stub  zone  is
253              set to prime, without it it is set to notprime.  The addr can be
254              IP4, IP6 or nameserver  names,  like  the  stub-zone  config  in
255              unbound.conf.
256
257       stub_remove [+i] zone
258              Remove  a stub zone from running unbound.  The +i also removes a
259              domain-insecure for the zone.
260
261       forward [off | addr ... ]
262              Setup forwarding mode.  Configures  if  the  server  should  ask
263              other upstream nameservers, should go to the internet root name‐
264              servers itself, or show the current config.  You could pass  the
265              nameservers after a DHCP update.
266
267              Without  arguments the current list of addresses used to forward
268              all queries to is printed.  On startup this  is  from  the  for‐
269              ward-zone  "."  configuration.   Afterwards it shows the status.
270              It prints off when no forwarding is used.
271
272              If off is passed, forwarding is  disabled  and  the  root  name‐
273              servers  are  used.  This can be used to avoid to avoid buggy or
274              non-DNSSEC supporting nameservers returned from DHCP.   But  may
275              not work in hotels or hotspots.
276
277              If  one or more IPv4 or IPv6 addresses are given, those are then
278              used to forward queries to.  The  addresses  must  be  separated
279              with spaces.  With '@port' the port number can be set explicitly
280              (default port is 53 (DNS)).
281
282              By default the forwarder information from the  config  file  for
283              the  root "." is used.  The config file is not changed, so after
284              a reload these changes are gone.  Other forward zones  from  the
285              config file are not affected by this command.
286
287       ratelimit_list [+a]
288              List  the  domains  that  are ratelimited.  Printed one per line
289              with current estimated qps and qps limit from config.   With  +a
290              it  prints  all  domains, not just the ratelimited domains, with
291              their estimated qps.  The ratelimited domains  return  an  error
292              for uncached (new) queries, but cached queries work as normal.
293
294       ip_ratelimit_list [+a]
295              List  the  ip  addresses  that are ratelimited.  Printed one per
296              line with current estimated qps and qps limit from config.  With
297              +a  it  prints all ips, not just the ratelimited ips, with their
298              estimated qps.  The ratelimited ips are dropped before  checking
299              the cache.
300
301       list_auth_zones
302              List  the  auth zones that are configured.  Printed one per line
303              with a status, indicating if the zone  is  expired  and  current
304              serial number.
305
306       view_list_local_zones view
307              list_local_zones for given view.
308
309       view_local_zone view name type
310              local_zone for given view.
311
312       view_local_zone_remove view name
313              local_zone_remove for given view.
314
315       view_list_local_data view
316              list_local_data for given view.
317
318       view_local_data view RR data...
319              local_data for given view.
320
321       view_local_data_remove view name
322              local_data_remove for given view.
323

EXIT CODE

325       The  unbound-control  program  exits  with status code 1 on error, 0 on
326       success.
327

SET UP

329       The setup requires a self-signed certificate and private keys for  both
330       the  server  and  client.   The  script unbound-control-setup generates
331       these in the default run directory, or with -d  in  another  directory.
332       If  you  change the access control permissions on the key files you can
333       decide who can use unbound-control, by default owner and group but  not
334       all  users.  Run the script under the same username as you have config‐
335       ured in unbound.conf or as root, so that the  daemon  is  permitted  to
336       read the files, for example with:
337           sudo -u unbound unbound-control-setup
338       If  you  have  not configured a username in unbound.conf, the keys need
339       read permission for the user credentials  under  which  the  daemon  is
340       started.   The  script preserves private keys present in the directory.
341       After  running  the  script  as  root,  turn   on   control-enable   in
342       unbound.conf.
343

STATISTIC COUNTERS

345       The stats command shows a number of statistic counters.
346
347       threadX.num.queries
348              number of queries received by thread
349
350       threadX.num.queries_ip_ratelimited
351              number of queries rate limited by thread
352
353       threadX.num.cachehits
354              number  of queries that were successfully answered using a cache
355              lookup
356
357       threadX.num.cachemiss
358              number of queries that needed recursive processing
359
360       threadX.num.dnscrypt.crypted
361              number of queries that were encrypted and successfully  decapsu‐
362              lated by dnscrypt.
363
364       threadX.num.dnscrypt.cert
365              number of queries that were requesting dnscrypt certificates.
366
367       threadX.num.dnscrypt.cleartext
368              number  of queries received on dnscrypt port that were cleartext
369              and not a request for certificates.
370
371       threadX.num.dnscrypt.malformed
372              number  of  request  that  were  neither  cleartext,  not  valid
373              dnscrypt messages.
374
375       threadX.num.prefetch
376              number  of  cache prefetches performed.  This number is included
377              in cachehits, as the original query had the unprefetched  answer
378              from  cache, and resulted in recursive processing, taking a slot
379              in the requestlist.  Not part of the  recursivereplies  (or  the
380              histogram thereof) or cachemiss, as a cache response was sent.
381
382       threadX.num.zero_ttl
383              number  of replies with ttl zero, because they served an expired
384              cache entry.
385
386       threadX.num.recursivereplies
387              The number of replies sent to queries that needed recursive pro‐
388              cessing.  Could  be smaller than threadX.num.cachemiss if due to
389              timeouts no replies were sent for some queries.
390
391       threadX.requestlist.avg
392              The average number of requests in the  internal  recursive  pro‐
393              cessing  request list on insert of a new incoming recursive pro‐
394              cessing query.
395
396       threadX.requestlist.max
397              Maximum size  attained  by  the  internal  recursive  processing
398              request list.
399
400       threadX.requestlist.overwritten
401              Number  of requests in the request list that were overwritten by
402              newer entries. This happens if there is a flood of queries  that
403              recursive processing and the server has a hard time.
404
405       threadX.requestlist.exceeded
406              Queries  that  were  dropped  because the request list was full.
407              This happens if a flood of queries  need  recursive  processing,
408              and the server can not keep up.
409
410       threadX.requestlist.current.all
411              Current  size of the request list, includes internally generated
412              queries (such as priming queries and glue lookups).
413
414       threadX.requestlist.current.user
415              Current size of the request list, only the requests from  client
416              queries.
417
418       threadX.recursion.time.avg
419              Average  time  it  took  to answer queries that needed recursive
420              processing. Note that queries that were answered from the  cache
421              are not in this average.
422
423       threadX.recursion.time.median
424              The  median  of  the  time it took to answer queries that needed
425              recursive processing.  The median means that  50%  of  the  user
426              queries  were  answered  in less than this time.  Because of big
427              outliers (usually queries to non responsive servers), the  aver‐
428              age  can be bigger than the median.  This median has been calcu‐
429              lated by interpolation from a histogram.
430
431       threadX.tcpusage
432              The currently held tcp buffers for incoming connections.  A spot
433              value  on  the  time of the request.  This helps you spot if the
434              incoming-num-tcp buffers are full.
435
436       total.num.queries
437              summed over threads.
438
439       total.num.cachehits
440              summed over threads.
441
442       total.num.cachemiss
443              summed over threads.
444
445       total.num.dnscrypt.crypted
446              summed over threads.
447
448       total.num.dnscrypt.cert
449              summed over threads.
450
451       total.num.dnscrypt.cleartext
452              summed over threads.
453
454       total.num.dnscrypt.malformed
455              summed over threads.
456
457       total.num.prefetch
458              summed over threads.
459
460       total.num.zero_ttl
461              summed over threads.
462
463       total.num.recursivereplies
464              summed over threads.
465
466       total.requestlist.avg
467              averaged over threads.
468
469       total.requestlist.max
470              the maximum of the thread requestlist.max values.
471
472       total.requestlist.overwritten
473              summed over threads.
474
475       total.requestlist.exceeded
476              summed over threads.
477
478       total.requestlist.current.all
479              summed over threads.
480
481       total.recursion.time.median
482              averaged over threads.
483
484       total.tcpusage
485              summed over threads.
486
487       time.now
488              current time in seconds since 1970.
489
490       time.up
491              uptime since server boot in seconds.
492
493       time.elapsed
494              time since last statistics printout, in seconds.
495

EXTENDED STATISTICS

497       mem.cache.rrset
498              Memory in bytes in use by the RRset cache.
499
500       mem.cache.message
501              Memory in bytes in use by the message cache.
502
503       mem.cache.dnscrypt_shared_secret
504              Memory in bytes in use by the dnscrypt shared secrets cache.
505
506       mem.cache.dnscrypt_nonce
507              Memory in bytes in use by the dnscrypt nonce cache.
508
509       mem.mod.iterator
510              Memory in bytes in use by the iterator module.
511
512       mem.mod.validator
513              Memory in bytes in use by the validator module. Includes the key
514              cache and negative cache.
515
516       histogram.<sec>.<usec>.to.<sec>.<usec>
517              Shows a histogram, summed over all threads. Every element counts
518              the recursive queries whose reply time fit between the lower and
519              upper  bound.   Times  larger  or  equal  to the lowerbound, and
520              smaller than the upper bound.  There are 40 buckets, with bucket
521              sizes doubling.
522
523       num.query.type.A
524              The  total number of queries over all threads with query type A.
525              Printed for the other query types as  well,  but  only  for  the
526              types for which queries were received, thus =0 entries are omit‐
527              ted for brevity.
528
529       num.query.type.other
530              Number of queries with query types 256-65535.
531
532       num.query.class.IN
533              The total number of queries over all threads with query class IN
534              (internet).   Also printed for other classes (such as CH (CHAOS)
535              sometimes used for debugging), or NONE,  ANY,  used  by  dynamic
536              update.  num.query.class.other is printed for classes 256-65535.
537
538       num.query.opcode.QUERY
539              The  total  number of queries over all threads with query opcode
540              QUERY.  Also printed for other opcodes, UPDATE, ...
541
542       num.query.tcp
543              Number of queries that were made using TCP towards  the  unbound
544              server.
545
546       num.query.tcpout
547              Number  of queries that the unbound server made using TCP outgo‐
548              ing towards other servers.
549
550       num.query.ipv6
551              Number of queries that were made using IPv6 towards the  unbound
552              server.
553
554       num.query.flags.RD
555              The  number  of  queries that had the RD flag set in the header.
556              Also printed for flags QR, AA, TC, RA, Z,  AD,  CD.   Note  that
557              queries  with  flags QR, AA or TC may have been rejected because
558              of that.
559
560       num.query.edns.present
561              number of queries that had an EDNS OPT record present.
562
563       num.query.edns.DO
564              number of queries that had  an  EDNS  OPT  record  with  the  DO
565              (DNSSEC  OK)  bit  set.   These queries are also included in the
566              num.query.edns.present number.
567
568       num.query.ratelimited
569              The number of queries that are turned away from  being  send  to
570              nameserver due to ratelimiting.
571
572       num.query.dnscrypt.shared_secret.cachemiss
573              The number of dnscrypt queries that did not find a shared secret
574              in the cache.  The can be  use  to  compute  the  shared  secret
575              hitrate.
576
577       num.query.dnscrypt.replay
578              The  number  of  dnscrypt  queries that found a nonce hit in the
579              nonce cache and hence are considered a query replay.
580
581       num.answer.rcode.NXDOMAIN
582              The number of answers to queries, from cache or from  recursion,
583              that  had  the  return code NXDOMAIN. Also printed for the other
584              return codes.
585
586       num.answer.rcode.nodata
587              The number of answers to queries that had the pseudo return code
588              nodata.   This  means  the  actual  return code was NOERROR, but
589              additionally, no data was carried in the answer (making what  is
590              called   a  NOERROR/NODATA  answer).   These  queries  are  also
591              included in the  num.answer.rcode.NOERROR  number.   Common  for
592              AAAA lookups when an A record exists, and no AAAA.
593
594       num.answer.secure
595              Number  of  answers that were secure.  The answer validated cor‐
596              rectly.  The AD bit  might  have  been  set  in  some  of  these
597              answers,  where  the  client signalled (with DO or AD bit in the
598              query) that they were ready to accept the AD bit in the answer.
599
600       num.answer.bogus
601              Number of answers that were bogus.  These  answers  resulted  in
602              SERVFAIL to the client because the answer failed validation.
603
604       num.rrset.bogus
605              The  number  of rrsets marked bogus by the validator.  Increased
606              for every RRset inspection that fails.
607
608       unwanted.queries
609              Number of queries that were  refused  or  dropped  because  they
610              failed the access control settings.
611
612       unwanted.replies
613              Replies that were unwanted or unsolicited.  Could have been ran‐
614              dom traffic, delayed duplicates, very late answers, or could  be
615              spoofing  attempts.   Some low level of late answers and delayed
616              duplicates are to be expected with the UDP protocol.  Very  high
617              values could indicate a threat (spoofing).
618
619       msg.cache.count
620              The number of items (DNS replies) in the message cache.
621
622       rrset.cache.count
623              The  number  of RRsets in the rrset cache.  This includes rrsets
624              used by the messages in the message cache, but  also  delegation
625              information.
626
627       infra.cache.count
628              The  number of items in the infra cache.  These are IP addresses
629              with their timing and protocol support information.
630
631       key.cache.count
632              The number of items in the key cache.  These  are  DNSSEC  keys,
633              one item per delegation point, and their validation status.
634
635       dnscrypt_shared_secret.cache.count
636              The  number  of items in the shared secret cache. These are pre‐
637              computed shared secrets for a  given  client  public  key/server
638              secret key pair. Shared secrets are CPU intensive and this cache
639              allows unbound to avoid recomputing the shared secret when  mul‐
640              tiple dnscrypt queries are sent from the same client.
641
642       dnscrypt_nonce.cache.count
643              The  number  of  items  in the client nonce cache. This cache is
644              used to prevent dnscrypt queries replay. The client  nonce  must
645              be  unique  for  each  client public key/server secret key pair.
646              This cache should be able to host QPS * `replay window` interval
647              keys  to  prevent  replay of a query during `replay window` sec‐
648              onds.
649
650       num.query.authzone.up
651              The number of queries answered  from  auth-zone  data,  upstream
652              queries.   These  queries  would  otherwise have been sent (with
653              fallback enabled) to the internet, but are now answered from the
654              auth zone.
655
656       num.query.authzone.down
657              The  number  of  queries  for downstream answered from auth-zone
658              data.  These queries are from downstream clients, and  have  had
659              an answer from the data in the auth zone.
660
661       num.query.aggressive.NOERROR
662              The  number  of  queries answered using cached NSEC records with
663              NODATA RCODE.  These queries would otherwise have been  sent  to
664              the internet, but are now answered using cached data.
665
666       num.query.aggressive.NXDOMAIN
667              The  number  of  queries answered using cached NSEC records with
668              NXDOMAIN RCODE.  These queries would otherwise have been sent to
669              the internet, but are now answered using cached data.
670

FILES

672       /etc/unbound/unbound.conf
673              unbound configuration file.
674
675       /etc/unbound
676              directory with private keys (unbound_server.key and unbound_con‐
677              trol.key) and self-signed certificates  (unbound_server.pem  and
678              unbound_control.pem).
679

SEE ALSO

681       unbound.conf(5), unbound(8).
682
683
684
685NLnet Labs                       Jun 21, 2018               unbound-control(8)
Impressum