contrib/unbound/doc/unbound-control.8.in

   1 .TH "unbound-control" "8" "Nov  8, 2023" "NLnet Labs" "unbound 1.19.0"
   2 .\"
   3 .\" unbound-control.8 -- unbound remote control manual
   4 .\"
   5 .\" Copyright (c) 2008, NLnet Labs. All rights reserved.
   6 .\"
   7 .\" See LICENSE for the license.
   8 .\"
   9 .\"
  10 .SH "NAME"
  11 .B unbound\-control,
  12 .B unbound\-control\-setup
  13 \- Unbound remote server control utility.
  14 .SH "SYNOPSIS"
  15 .B unbound\-control
  16 .RB [ \-hq ]
  17 .RB [ \-c
  18 .IR cfgfile ]
  19 .RB [ \-s
  20 .IR server ]
  21 .IR command
  22 .SH "DESCRIPTION"
  23 .B Unbound\-control
  24 performs remote administration on the \fIunbound\fR(8) DNS server.
  25 It reads the configuration file, contacts the Unbound server over SSL
  26 sends the command and displays the result.
  27 .P
  28 The available options are:
  29 .TP
  30 .B \-h
  31 Show the version and commandline option help.
  32 .TP
  33 .B \-c \fIcfgfile
  34 The config file to read with settings.  If not given the default
  35 config file @ub_conf_file@ is used.
  36 .TP
  37 .B \-s \fIserver[@port]
  38 IPv4 or IPv6 address of the server to contact.  If not given, the
  39 address is read from the config file.
  40 .TP
  41 .B \-q
  42 quiet, if the option is given it does not print anything if it works ok.
  43 .SH "COMMANDS"
  44 There are several commands that the server understands.
  45 .TP
  46 .B start
  47 Start the server. Simply execs \fIunbound\fR(8).  The Unbound executable
  48 is searched for in the \fBPATH\fR set in the environment.  It is started
  49 with the config file specified using \fI\-c\fR or the default config file.
  50 .TP
  51 .B stop
  52 Stop the server. The server daemon exits.
  53 .TP
  54 .B reload
  55 Reload the server. This flushes the cache and reads the config file fresh.
  56 .TP
  57 .B reload_keep_cache
  58 Reload the server but try to keep the RRset and message cache if
  59 (re)configuration allows for it.
  60 That means the caches sizes and the number of threads must not change between
  61 reloads.
  62 .TP
  63 .B verbosity \fInumber
  64 Change verbosity value for logging. Same values as \fBverbosity\fR keyword in
  65 \fIunbound.conf\fR(5).  This new setting lasts until the server is issued
  66 a reload (taken from config file again), or the next verbosity control command.
  67 .TP
  68 .B log_reopen
  69 Reopen the logfile, close and open it.  Useful for logrotation to make the
  70 daemon release the file it is logging to.  If you are using syslog it will
  71 attempt to close and open the syslog (which may not work if chrooted).
  72 .TP
  73 .B stats
  74 Print statistics. Resets the internal counters to zero, this can be
  75 controlled using the \fBstatistics\-cumulative\fR config statement.
  76 Statistics are printed with one [name]: [value] per line.
  77 .TP
  78 .B stats_noreset
  79 Peek at statistics. Prints them like the \fBstats\fR command does, but does not
  80 reset the internal counters to zero.
  81 .TP
  82 .B status
  83 Display server status. Exit code 3 if not running (the connection to the
  84 port is refused), 1 on error, 0 if running.
  85 .TP
  86 .B local_zone \fIname\fR \fItype
  87 Add new local zone with name and type. Like \fBlocal\-zone\fR config statement.
  88 If the zone already exists, the type is changed to the given argument.
  89 .TP
  90 .B local_zone_remove \fIname
  91 Remove the local zone with the given name.  Removes all local data inside
  92 it.  If the zone does not exist, the command succeeds.
  93 .TP
  94 .B local_data \fIRR data...
  95 Add new local data, the given resource record. Like \fBlocal\-data\fR
  96 config statement, except for when no covering zone exists.  In that case
  97 this remote control command creates a transparent zone with the same
  98 name as this record.
  99 .TP
 100 .B local_data_remove \fIname
 101 Remove all RR data from local name.  If the name already has no items,
 102 nothing happens.  Often results in NXDOMAIN for the name (in a static zone),
 103 but if the name has become an empty nonterminal (there is still data in
 104 domain names below the removed name), NOERROR nodata answers are the
 105 result for that name.
 106 .TP
 107 .B local_zones
 108 Add local zones read from stdin of unbound\-control. Input is read per line,
 109 with name space type on a line. For bulk additions.
 110 .TP
 111 .B local_zones_remove
 112 Remove local zones read from stdin of unbound\-control. Input is one name per
 113 line. For bulk removals.
 114 .TP
 115 .B local_datas
 116 Add local data RRs read from stdin of unbound\-control. Input is one RR per
 117 line. For bulk additions.
 118 .TP
 119 .B local_datas_remove
 120 Remove local data RRs read from stdin of unbound\-control. Input is one name per
 121 line. For bulk removals.
 122 .TP
 123 .B dump_cache
 124 The contents of the cache is printed in a text format to stdout. You can
 125 redirect it to a file to store the cache in a file.
 126 .TP
 127 .B load_cache
 128 The contents of the cache is loaded from stdin.  Uses the same format as
 129 dump_cache uses.  Loading the cache with old, or wrong data can result
 130 in old or wrong data returned to clients.  Loading data into the cache
 131 in this way is supported in order to aid with debugging.
 132 .TP
 133 .B lookup \fIname
 134 Print to stdout the name servers that would be used to look up the
 135 name specified.
 136 .TP
 137 .B flush \fIname
 138 Remove the name from the cache. Removes the types
 139 A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV, NAPTR, SVCB and HTTPS.
 140 Because that is fast to do. Other record types can be removed using
 141 .B flush_type
 142 or
 143 .B flush_zone\fR.
 144 .TP
 145 .B flush_type \fIname\fR \fItype
 146 Remove the name, type information from the cache.
 147 .TP
 148 .B flush_zone \fIname
 149 Remove all information at or below the name from the cache.
 150 The rrsets and key entries are removed so that new lookups will be performed.
 151 This needs to walk and inspect the entire cache, and is a slow operation.
 152 The entries are set to expired in the implementation of this command (so,
 153 with serve\-expired enabled, it'll serve that information but schedule a
 154 prefetch for new information).
 155 .TP
 156 .B flush_bogus
 157 Remove all bogus data from the cache.
 158 .TP
 159 .B flush_negative
 160 Remove all negative data from the cache.  This is nxdomain answers,
 161 nodata answers and servfail answers.  Also removes bad key entries
 162 (which could be due to failed lookups) from the dnssec key cache, and
 163 iterator last-resort lookup failures from the rrset cache.
 164 .TP
 165 .B flush_stats
 166 Reset statistics to zero.
 167 .TP
 168 .B flush_requestlist
 169 Drop the queries that are worked on.  Stops working on the queries that the
 170 server is working on now.  The cache is unaffected.  No reply is sent for
 171 those queries, probably making those users request again later.
 172 Useful to make the server restart working on queries with new settings,
 173 such as a higher verbosity level.
 174 .TP
 175 .B dump_requestlist
 176 Show what is worked on.  Prints all queries that the server is currently
 177 working on.  Prints the time that users have been waiting.  For internal
 178 requests, no time is printed.  And then prints out the module status.
 179 This prints the queries from the first thread, and not queries that are
 180 being serviced from other threads.
 181 .TP
 182 .B flush_infra \fIall|IP
 183 If all then entire infra cache is emptied.  If a specific IP address, the
 184 entry for that address is removed from the cache.  It contains EDNS, ping
 185 and lameness data.
 186 .TP
 187 .B dump_infra
 188 Show the contents of the infra cache.
 189 .TP
 190 .B set_option \fIopt: val
 191 Set the option to the given value without a reload.  The cache is
 192 therefore not flushed.  The option must end with a ':' and whitespace
 193 must be between the option and the value.  Some values may not have an
 194 effect if set this way, the new values are not written to the config file,
 195 not all options are supported.  This is different from the set_option call
 196 in libunbound, where all values work because Unbound has not been initialized.
 197 .IP
 198 The values that work are: statistics\-interval, statistics\-cumulative,
 199 do\-not\-query\-localhost, harden\-short\-bufsize, harden\-large\-queries,
 200 harden\-glue, harden\-dnssec\-stripped, harden\-below\-nxdomain,
 201 harden\-referral\-path, prefetch, prefetch\-key, log\-queries,
 202 hide\-identity, hide\-version, identity, version, val\-log\-level,
 203 val\-log\-squelch, ignore\-cd\-flag, add\-holddown, del\-holddown,
 204 keep\-missing, tcp\-upstream, ssl\-upstream, max\-udp\-size, ratelimit,
 205 ip\-ratelimit, cache\-max\-ttl, cache\-min\-ttl, cache\-max\-negative\-ttl.
 206 .TP
 207 .B get_option \fIopt
 208 Get the value of the option.  Give the option name without a trailing ':'.
 209 The value is printed.  If the value is "", nothing is printed
 210 and the connection closes.  On error 'error ...' is printed (it gives
 211 a syntax error on unknown option).  For some options a list of values,
 212 one on each line, is printed.  The options are shown from the config file
 213 as modified with set_option.  For some options an override may have been
 214 taken that does not show up with this command, not results from e.g. the
 215 verbosity and forward control commands.  Not all options work, see list_stubs,
 216 list_forwards, list_local_zones and list_local_data for those.
 217 .TP
 218 .B list_stubs
 219 List the stub zones in use.  These are printed one by one to the output.
 220 This includes the root hints in use.
 221 .TP
 222 .B list_forwards
 223 List the forward zones in use.  These are printed zone by zone to the output.
 224 .TP
 225 .B list_insecure
 226 List the zones with domain\-insecure.
 227 .TP
 228 .B list_local_zones
 229 List the local zones in use.  These are printed one per line with zone type.
 230 .TP
 231 .B list_local_data
 232 List the local data RRs in use.  The resource records are printed.
 233 .TP
 234 .B insecure_add \fIzone
 235 Add a \fBdomain\-insecure\fR for the given zone, like the statement in unbound.conf.
 236 Adds to the running Unbound without affecting the cache contents (which may
 237 still be bogus, use \fBflush_zone\fR to remove it), does not affect the config file.
 238 .TP
 239 .B insecure_remove \fIzone
 240 Removes domain\-insecure for the given zone.
 241 .TP
 242 .B forward_add \fR[\fI+i\fR] \fIzone addr ...
 243 Add a new forward zone to running Unbound.  With +i option also adds a
 244 \fIdomain\-insecure\fR for the zone (so it can resolve insecurely if you have
 245 a DNSSEC root trust anchor configured for other names).
 246 The addr can be IP4, IP6 or nameserver names, like \fIforward-zone\fR config
 247 in unbound.conf.
 248 .TP
 249 .B forward_remove \fR[\fI+i\fR] \fIzone
 250 Remove a forward zone from running Unbound.  The +i also removes a
 251 \fIdomain\-insecure\fR for the zone.
 252 .TP
 253 .B stub_add \fR[\fI+ip\fR] \fIzone addr ...
 254 Add a new stub zone to running Unbound.  With +i option also adds a
 255 \fIdomain\-insecure\fR for the zone.  With +p the stub zone is set to prime,
 256 without it it is set to notprime.  The addr can be IP4, IP6 or nameserver
 257 names, like the \fIstub-zone\fR config in unbound.conf.
 258 .TP
 259 .B stub_remove \fR[\fI+i\fR] \fIzone
 260 Remove a stub zone from running Unbound.  The +i also removes a
 261 \fIdomain\-insecure\fR for the zone.
 262 .TP
 263 .B forward \fR[\fIoff\fR | \fIaddr ...\fR ]
 264 Setup forwarding mode.  Configures if the server should ask other upstream
 265 nameservers, should go to the internet root nameservers itself, or show
 266 the current config.  You could pass the nameservers after a DHCP update.
 267 .IP
 268 Without arguments the current list of addresses used to forward all queries
 269 to is printed.  On startup this is from the forward\-zone "." configuration.
 270 Afterwards it shows the status.  It prints off when no forwarding is used.
 271 .IP
 272 If \fIoff\fR is passed, forwarding is disabled and the root nameservers
 273 are used.  This can be used to avoid to avoid buggy or non\-DNSSEC supporting
 274 nameservers returned from DHCP.  But may not work in hotels or hotspots.
 275 .IP
 276 If one or more IPv4 or IPv6 addresses are given, those are then used to forward
 277 queries to.  The addresses must be separated with spaces.  With '@port' the
 278 port number can be set explicitly (default port is 53 (DNS)).
 279 .IP
 280 By default the forwarder information from the config file for the root "." is
 281 used.  The config file is not changed, so after a reload these changes are
 282 gone.  Other forward zones from the config file are not affected by this command.
 283 .TP
 284 .B ratelimit_list \fR[\fI+a\fR]
 285 List the domains that are ratelimited.  Printed one per line with current
 286 estimated qps and qps limit from config.  With +a it prints all domains, not
 287 just the ratelimited domains, with their estimated qps.  The ratelimited
 288 domains return an error for uncached (new) queries, but cached queries work
 289 as normal.
 290 .TP
 291 .B ip_ratelimit_list \fR[\fI+a\fR]
 292 List the ip addresses that are ratelimited.  Printed one per line with current
 293 estimated qps and qps limit from config.  With +a it prints all ips, not
 294 just the ratelimited ips, with their estimated qps.  The ratelimited
 295 ips are dropped before checking the cache.
 296 .TP
 297 .B list_auth_zones
 298 List the auth zones that are configured.  Printed one per line with a status,
 299 indicating if the zone is expired and current serial number.  Configured RPZ
 300 zones are included.
 301 .TP
 302 .B auth_zone_reload \fIzone\fR
 303 Reload the auth zone (or RPZ zone) from zonefile.  The zonefile is read in
 304 overwriting the current contents of the zone in memory.  This changes the auth
 305 zone contents itself, not the cache contents.  Such cache contents exists if
 306 you set Unbound to validate with for-upstream yes and that can be cleared with
 307 \fBflush_zone\fR \fIzone\fR.
 308 .TP
 309 .B auth_zone_transfer \fIzone\fR
 310 Transfer the auth zone (or RPZ zone) from master.  The auth zone probe sequence
 311 is started, where the masters are probed to see if they have an updated zone
 312 (with the SOA serial check).  And then the zone is transferred for a newer zone
 313 version.
 314 .TP
 315 .B rpz_enable \fIzone\fR
 316 Enable the RPZ zone if it had previously been disabled.
 317 .TP
 318 .B rpz_disable \fIzone\fR
 319 Disable the RPZ zone.
 320 .TP
 321 .B view_list_local_zones \fIview\fR
 322 \fIlist_local_zones\fR for given view.
 323 .TP
 324 .B view_local_zone \fIview\fR \fIname\fR \fItype
 325 \fIlocal_zone\fR for given view.
 326 .TP
 327 .B view_local_zone_remove \fIview\fR \fIname
 328 \fIlocal_zone_remove\fR for given view.
 329 .TP
 330 .B view_list_local_data \fIview\fR
 331 \fIlist_local_data\fR for given view.
 332 .TP
 333 .B view_local_data \fIview\fR \fIRR data...
 334 \fIlocal_data\fR for given view.
 335 .TP
 336 .B view_local_data_remove \fIview\fR \fIname
 337 \fIlocal_data_remove\fR for given view.
 338 .TP
 339 .B view_local_datas_remove \fIview\fR
 340 Remove a list of \fIlocal_data\fR for given view from stdin. Like local_datas_remove.
 341 .TP
 342 .B view_local_datas \fIview\fR
 343 Add a list of \fIlocal_data\fR for given view from stdin.  Like local_datas.
 344 .SH "EXIT CODE"
 345 The unbound\-control program exits with status code 1 on error, 0 on success.
 346 .SH "SET UP"
 347 The setup requires a self\-signed certificate and private keys for both
 348 the server and client.  The script \fIunbound\-control\-setup\fR generates
 349 these in the default run directory, or with \-d in another directory.
 350 If you change the access control permissions on the key files you can decide
 351 who can use unbound\-control, by default owner and group but not all users.
 352 Run the script under the same username as you have configured in unbound.conf
 353 or as root, so that the daemon is permitted to read the files, for example with:
 354 .nf
 355     sudo \-u unbound unbound\-control\-setup
 356 .fi
 357 If you have not configured
 358 a username in unbound.conf, the keys need read permission for the user
 359 credentials under which the daemon is started.
 360 The script preserves private keys present in the directory.
 361 After running the script as root, turn on \fBcontrol\-enable\fR in
 362 \fIunbound.conf\fR.
 363 .SH "STATISTIC COUNTERS"
 364 The \fIstats\fR command shows a number of statistic counters.
 365 .TP
 366 .I threadX.num.queries
 367 number of queries received by thread
 368 .TP
 369 .I threadX.num.queries_ip_ratelimited
 370 number of queries rate limited by thread
 371 .TP
 372 .I threadX.num.queries_cookie_valid
 373 number of queries with a valid DNS Cookie by thread
 374 .TP
 375 .I threadX.num.queries_cookie_client
 376 number of queries with a client part only DNS Cookie by thread
 377 .TP
 378 .I threadX.num.queries_cookie_invalid
 379 number of queries with an invalid DNS Cookie by thread
 380 .TP
 381 .I threadX.num.cachehits
 382 number of queries that were successfully answered using a cache lookup
 383 .TP
 384 .I threadX.num.cachemiss
 385 number of queries that needed recursive processing
 386 .TP
 387 .I threadX.num.dnscrypt.crypted
 388 number of queries that were encrypted and successfully decapsulated by dnscrypt.
 389 .TP
 390 .I threadX.num.dnscrypt.cert
 391 number of queries that were requesting dnscrypt certificates.
 392 .TP
 393 .I threadX.num.dnscrypt.cleartext
 394 number of queries received on dnscrypt port that were cleartext and not a
 395 request for certificates.
 396 .TP
 397 .I threadX.num.dnscrypt.malformed
 398 number of request that were neither cleartext, not valid dnscrypt messages.
 399 .TP
 400 .I threadX.num.prefetch
 401 number of cache prefetches performed.  This number is included in
 402 cachehits, as the original query had the unprefetched answer from cache,
 403 and resulted in recursive processing, taking a slot in the requestlist.
 404 Not part of the recursivereplies (or the histogram thereof) or cachemiss,
 405 as a cache response was sent.
 406 .TP
 407 .I threadX.num.expired
 408 number of replies that served an expired cache entry.
 409 .TP
 410 .I threadX.num.queries_timed_out
 411 number of queries that are dropped because they waited in the UDP socket buffer
 412 for too long.
 413 .TP
 414 .I threadX.query.queue_time_us.max
 415 The maximum wait time for packets in the socket buffer, in microseconds. This
 416 is only reported when sock-queue-timeout is enabled.
 417 .TP
 418 .I threadX.num.recursivereplies
 419 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.
 420 .TP
 421 .I threadX.requestlist.avg
 422 The average number of requests in the internal recursive processing request list on insert of a new incoming recursive processing query.
 423 .TP
 424 .I threadX.requestlist.max
 425 Maximum size attained by the internal recursive processing request list.
 426 .TP
 427 .I threadX.requestlist.overwritten
 428 Number of requests in the request list that were overwritten by newer entries. This happens if there is a flood of queries that recursive processing and the server has a hard time.
 429 .TP
 430 .I threadX.requestlist.exceeded
 431 Queries that were dropped because the request list was full. This happens if a flood of queries need recursive processing, and the server can not keep up.
 432 .TP
 433 .I threadX.requestlist.current.all
 434 Current size of the request list, includes internally generated queries (such
 435 as priming queries and glue lookups).
 436 .TP
 437 .I threadX.requestlist.current.user
 438 Current size of the request list, only the requests from client queries.
 439 .TP
 440 .I threadX.recursion.time.avg
 441 Average time it took to answer queries that needed recursive processing. Note that queries that were answered from the cache are not in this average.
 442 .TP
 443 .I threadX.recursion.time.median
 444 The median of the time it took to answer queries that needed recursive
 445 processing.  The median means that 50% of the user queries were answered in
 446 less than this time.  Because of big outliers (usually queries to non
 447 responsive servers), the average can be bigger than the median.  This median
 448 has been calculated by interpolation from a histogram.
 449 .TP
 450 .I threadX.tcpusage
 451 The currently held tcp buffers for incoming connections.  A spot value on
 452 the time of the request.  This helps you spot if the incoming\-num\-tcp
 453 buffers are full.
 454 .TP
 455 .I total.num.queries
 456 summed over threads.
 457 .TP
 458 .I total.num.queries_ip_ratelimited
 459 summed over threads.
 460 .TP
 461 .I total.num.queries_cookie_valid
 462 summed over threads.
 463 .TP
 464 .I total.num.queries_cookie_client
 465 summed over threads.
 466 .TP
 467 .I total.num.queries_cookie_invalid
 468 summed over threads.
 469 .TP
 470 .I total.num.cachehits
 471 summed over threads.
 472 .TP
 473 .I total.num.cachemiss
 474 summed over threads.
 475 .TP
 476 .I total.num.dnscrypt.crypted
 477 summed over threads.
 478 .TP
 479 .I total.num.dnscrypt.cert
 480 summed over threads.
 481 .TP
 482 .I total.num.dnscrypt.cleartext
 483 summed over threads.
 484 .TP
 485 .I total.num.dnscrypt.malformed
 486 summed over threads.
 487 .TP
 488 .I total.num.prefetch
 489 summed over threads.
 490 .TP
 491 .I total.num.expired
 492 summed over threads.
 493 .TP
 494 .I total.num.queries_timed_out
 495 summed over threads.
 496 .TP
 497 .I total.query.queue_time_us.max
 498 the maximum of the thread values.
 499 .TP
 500 .I total.num.recursivereplies
 501 summed over threads.
 502 .TP
 503 .I total.requestlist.avg
 504 averaged over threads.
 505 .TP
 506 .I total.requestlist.max
 507 the maximum of the thread requestlist.max values.
 508 .TP
 509 .I total.requestlist.overwritten
 510 summed over threads.
 511 .TP
 512 .I total.requestlist.exceeded
 513 summed over threads.
 514 .TP
 515 .I total.requestlist.current.all
 516 summed over threads.
 517 .TP
 518 .I total.recursion.time.median
 519 averaged over threads.
 520 .TP
 521 .I total.tcpusage
 522 summed over threads.
 523 .TP
 524 .I time.now
 525 current time in seconds since 1970.
 526 .TP
 527 .I time.up
 528 uptime since server boot in seconds.
 529 .TP
 530 .I time.elapsed
 531 time since last statistics printout, in seconds.
 532 .SH EXTENDED STATISTICS
 533 .TP
 534 .I mem.cache.rrset
 535 Memory in bytes in use by the RRset cache.
 536 .TP
 537 .I mem.cache.message
 538 Memory in bytes in use by the message cache.
 539 .TP
 540 .I mem.cache.dnscrypt_shared_secret
 541 Memory in bytes in use by the dnscrypt shared secrets cache.
 542 .TP
 543 .I mem.cache.dnscrypt_nonce
 544 Memory in bytes in use by the dnscrypt nonce cache.
 545 .TP
 546 .I mem.mod.iterator
 547 Memory in bytes in use by the iterator module.
 548 .TP
 549 .I mem.mod.validator
 550 Memory in bytes in use by the validator module. Includes the key cache and
 551 negative cache.
 552 .TP
 553 .I mem.streamwait
 554 Memory in bytes in used by the TCP and TLS stream wait buffers.  These are
 555 answers waiting to be written back to the clients.
 556 .TP
 557 .I mem.http.query_buffer
 558 Memory in bytes used by the HTTP/2 query buffers. Containing (partial) DNS
 559 queries waiting for request stream completion.
 560 .TP
 561 .I mem.http.response_buffer
 562 Memory in bytes used by the HTTP/2 response buffers. Containing DNS responses
 563 waiting to be written back to the clients.
 564 .TP
 565 .I histogram.<sec>.<usec>.to.<sec>.<usec>
 566 Shows a histogram, summed over all threads. Every element counts the
 567 recursive queries whose reply time fit between the lower and upper bound.
 568 Times larger or equal to the lowerbound, and smaller than the upper bound.
 569 There are 40 buckets, with bucket sizes doubling.
 570 .TP
 571 .I num.query.type.A
 572 The total number of queries over all threads with query type A.
 573 Printed for the other query types as well, but only for the types for which
 574 queries were received, thus =0 entries are omitted for brevity.
 575 .TP
 576 .I num.query.type.other
 577 Number of queries with query types 256\-65535.
 578 .TP
 579 .I num.query.class.IN
 580 The total number of queries over all threads with query class IN (internet).
 581 Also printed for other classes (such as CH (CHAOS) sometimes used for
 582 debugging), or NONE, ANY, used by dynamic update.
 583 num.query.class.other is printed for classes 256\-65535.
 584 .TP
 585 .I num.query.opcode.QUERY
 586 The total number of queries over all threads with query opcode QUERY.
 587 Also printed for other opcodes, UPDATE, ...
 588 .TP
 589 .I num.query.tcp
 590 Number of queries that were made using TCP towards the Unbound server.
 591 .TP
 592 .I num.query.tcpout
 593 Number of queries that the Unbound server made using TCP outgoing towards
 594 other servers.
 595 .TP
 596 .I num.query.udpout
 597 Number of queries that the Unbound server made using UDP outgoing towards
 598 other servers.
 599 .TP
 600 .I num.query.tls
 601 Number of queries that were made using TLS towards the Unbound server.
 602 These are also counted in num.query.tcp, because TLS uses TCP.
 603 .TP
 604 .I num.query.tls.resume
 605 Number of TLS session resumptions, these are queries over TLS towards
 606 the Unbound server where the client negotiated a TLS session resumption key.
 607 .TP
 608 .I num.query.https
 609 Number of queries that were made using HTTPS towards the Unbound server.
 610 These are also counted in num.query.tcp and num.query.tls, because HTTPS
 611 uses TLS and TCP.
 612 .TP
 613 .I num.query.ipv6
 614 Number of queries that were made using IPv6 towards the Unbound server.
 615 .TP
 616 .I num.query.flags.RD
 617 The number of queries that had the RD flag set in the header.
 618 Also printed for flags QR, AA, TC, RA, Z, AD, CD.
 619 Note that queries with flags QR, AA or TC may have been rejected
 620 because of that.
 621 .TP
 622 .I num.query.edns.present
 623 number of queries that had an EDNS OPT record present.
 624 .TP
 625 .I num.query.edns.DO
 626 number of queries that had an EDNS OPT record with the DO (DNSSEC OK) bit set.
 627 These queries are also included in the num.query.edns.present number.
 628 .TP
 629 .I num.query.ratelimited
 630 The number of queries that are turned away from being send to nameserver due to
 631 ratelimiting.
 632 .TP
 633 .I num.query.dnscrypt.shared_secret.cachemiss
 634 The number of dnscrypt queries that did not find a shared secret in the cache.
 635 This can be used to compute the shared secret hitrate.
 636 .TP
 637 .I num.query.dnscrypt.replay
 638 The number of dnscrypt queries that found a nonce hit in the nonce cache and
 639 hence are considered a query replay.
 640 .TP
 641 .I num.answer.rcode.NXDOMAIN
 642 The number of answers to queries, from cache or from recursion, that had the
 643 return code NXDOMAIN. Also printed for the other return codes.
 644 .TP
 645 .I num.answer.rcode.nodata
 646 The number of answers to queries that had the pseudo return code nodata.
 647 This means the actual return code was NOERROR, but additionally, no data was
 648 carried in the answer (making what is called a NOERROR/NODATA answer).
 649 These queries are also included in the num.answer.rcode.NOERROR number.
 650 Common for AAAA lookups when an A record exists, and no AAAA.
 651 .TP
 652 .I num.answer.secure
 653 Number of answers that were secure.  The answer validated correctly.
 654 The AD bit might have been set in some of these answers, where the client
 655 signalled (with DO or AD bit in the query) that they were ready to accept
 656 the AD bit in the answer.
 657 .TP
 658 .I num.answer.bogus
 659 Number of answers that were bogus.  These answers resulted in SERVFAIL
 660 to the client because the answer failed validation.
 661 .TP
 662 .I num.rrset.bogus
 663 The number of rrsets marked bogus by the validator.  Increased for every
 664 RRset inspection that fails.
 665 .TP
 666 .I unwanted.queries
 667 Number of queries that were refused or dropped because they failed the
 668 access control settings.
 669 .TP
 670 .I unwanted.replies
 671 Replies that were unwanted or unsolicited.  Could have been random traffic,
 672 delayed duplicates, very late answers, or could be spoofing attempts.
 673 Some low level of late answers and delayed duplicates are to be expected
 674 with the UDP protocol.  Very high values could indicate a threat (spoofing).
 675 .TP
 676 .I msg.cache.count
 677 The number of items (DNS replies) in the message cache.
 678 .TP
 679 .I rrset.cache.count
 680 The number of RRsets in the rrset cache.  This includes rrsets used by
 681 the messages in the message cache, but also delegation information.
 682 .TP
 683 .I infra.cache.count
 684 The number of items in the infra cache.  These are IP addresses with their
 685 timing and protocol support information.
 686 .TP
 687 .I key.cache.count
 688 The number of items in the key cache.  These are DNSSEC keys, one item
 689 per delegation point, and their validation status.
 690 .TP
 691 .I msg.cache.max_collisions
 692 The maximum number of hash table collisions in the msg cache. This is the
 693 number of hashes that are identical when a new element is inserted in the
 694 hash table. If the value is very large, like hundreds, something is wrong
 695 with the performance of the hash table, hash values are incorrect or malicious.
 696 .TP
 697 .I rrset.cache.max_collisions
 698 The maximum number of hash table collisions in the rrset cache. This is the
 699 number of hashes that are identical when a new element is inserted in the
 700 hash table. If the value is very large, like hundreds, something is wrong
 701 with the performance of the hash table, hash values are incorrect or malicious.
 702 .TP
 703 .I dnscrypt_shared_secret.cache.count
 704 The number of items in the shared secret cache. These are precomputed shared
 705 secrets for a given client public key/server secret key pair. Shared secrets
 706 are CPU intensive and this cache allows Unbound to avoid recomputing the
 707 shared secret when multiple dnscrypt queries are sent from the same client.
 708 .TP
 709 .I dnscrypt_nonce.cache.count
 710 The number of items in the client nonce cache. This cache is used to prevent
 711 dnscrypt queries replay. The client nonce must be unique for each client public
 712 key/server secret key pair. This cache should be able to host QPS * `replay
 713 window` interval keys to prevent replay of a query during `replay window`
 714 seconds.
 715 .TP
 716 .I num.query.authzone.up
 717 The number of queries answered from auth\-zone data, upstream queries.
 718 These queries would otherwise have been sent (with fallback enabled) to
 719 the internet, but are now answered from the auth zone.
 720 .TP
 721 .I num.query.authzone.down
 722 The number of queries for downstream answered from auth\-zone data.
 723 These queries are from downstream clients, and have had an answer from
 724 the data in the auth zone.
 725 .TP
 726 .I num.query.aggressive.NOERROR
 727 The number of queries answered using cached NSEC records with NODATA RCODE.
 728 These queries would otherwise have been sent to the internet, but are now
 729 answered using cached data.
 730 .TP
 731 .I num.query.aggressive.NXDOMAIN
 732 The number of queries answered using cached NSEC records with NXDOMAIN RCODE.
 733 These queries would otherwise have been sent to the internet, but are now
 734 answered using cached data.
 735 .TP
 736 .I num.query.subnet
 737 Number of queries that got an answer that contained EDNS client subnet data.
 738 .TP
 739 .I num.query.subnet_cache
 740 Number of queries answered from the edns client subnet cache.  These are
 741 counted as cachemiss by the main counters, but hit the client subnet
 742 specific cache after getting processed by the edns client subnet module.
 743 .TP
 744 .I num.query.cachedb
 745 Number of queries answered from the external cache of cachedb.
 746 These are counted as cachemiss by the main counters, but hit the cachedb
 747 external cache after getting processed by the cachedb module.
 748 .TP
 749 .I num.rpz.action.<rpz_action>
 750 Number of queries answered using configured RPZ policy, per RPZ action type.
 751 Possible actions are: nxdomain, nodata, passthru, drop, tcp\-only, local\-data,
 752 disabled, and cname\-override.
 753 .SH "FILES"
 754 .TP
 755 .I @ub_conf_file@
 756 Unbound configuration file.
 757 .TP
 758 .I @UNBOUND_RUN_DIR@
 759 directory with private keys (unbound_server.key and unbound_control.key) and
 760 self\-signed certificates (unbound_server.pem and unbound_control.pem).
 761 .SH "SEE ALSO"
 762 \fIunbound.conf\fR(5),
 763 \fIunbound\fR(8).