Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
unbound-control(8)		unbound	1.5.10		    unbound-control(8)

NAME
       unbound-control,	 unbound-control-setup - Unbound remote	server control
       utility.

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

DESCRIPTION
       Unbound-control performs	remote administration on  the  unbound(8)  DNS
       server.	 It  reads the configuration file, contacts the	unbound	server
       over SSL	sends the command and displays the result.

       The available options are:

       -h     Show the version and commandline option help.

       -c cfgfile
	      The config file to read with settings.  If not given the default
	      config file /var/unbound/unbound.conf is used.

       -s server[@port]
	      IPv4  or	IPv6  address of the server to contact.	 If not	given,
	      the address is read from the config file.

       -q     quiet, if	the option is given it does not	print anything	if  it
	      works ok.

COMMANDS
       There are several commands that the server understands.

       start  Start  the  server.  Simply  execs unbound(8).  The unbound exe-
	      cutable is searched for in the PATH set in the environment.   It
	      is  started  with	 the config file specified using -c or the de-
	      fault config file.

       stop   Stop the server. The server daemon exits.

       reload Reload the server. This flushes the cache	and reads  the	config
	      file fresh.

       verbosity number
	      Change  verbosity	 value	for  logging. Same values as verbosity
	      keyword in unbound.conf(5).  This	new setting  lasts  until  the
	      server is	issued a reload	(taken from config file	again),	or the
	      next verbosity control command.

       log_reopen
	      Reopen the logfile, close	and open it.  Useful  for  logrotation
	      to  make	the  daemon release the	file it	is logging to.	If you
	      are using	syslog it will attempt to close	and  open  the	syslog
	      (which may not work if chrooted).

       stats  Print statistics.	Resets the internal counters to	zero, this can
	      be controlled using the statistics-cumulative config  statement.
	      Statistics are printed with one [name]: [value] per line.

       stats_noreset
	      Peek at statistics. Prints them like the stats command does, but
	      does not reset the internal counters to zero.

       status Display server status. Exit code 3 if not	running	 (the  connec-
	      tion to the port is refused), 1 on error,	0 if running.

       local_zone name type
	      Add  new	local  zone with name and type.	Like local-zone	config
	      statement.  If the zone already exists, the type is  changed  to
	      the given	argument.

       local_zone_remove name
	      Remove  the  local  zone with the	given name.  Removes all local
	      data inside it.  If the zone does	not exist,  the	 command  suc-
	      ceeds.

       local_data RR data...
	      Add  new	local data, the	given resource record. Like local-data
	      config statement,	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.  This command is not good  at
	      returning	detailed syntax	errors.

       local_data_remove name
	      Remove  all RR data from 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 nonter-
	      minal (there is still data in domain  names  below  the  removed
	      name), NOERROR nodata answers are	the result for that name.

       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.

       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.	 Load-
	      ing data into the	cache in this way is supported in order	to aid
	      with debugging.

       lookup name
	      Print to stdout the name servers that would be used to  look  up
	      the name specified.

       flush name
	      Remove  the  name	from the cache.	Removes	the types A, AAAA, NS,
	      SOA, CNAME, DNAME, MX, PTR, SRV and NAPTR.  Because that is fast
	      to  do.  Other  record  types can	be removed using flush_type or
	      flush_zone.

       flush_type name type
	      Remove the name, type information	from the cache.

       flush_zone name
	      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.

       flush_bogus
	      Remove all bogus data from the cache.

       flush_negative
	      Remove  all  negative data from the cache.  This is nxdomain an-
	      swers, nodata answers and	servfail answers.   Also  removes  bad
	      key  entries  (which  could  be  due to failed lookups) from the
	      dnssec key cache,	and iterator last-resort lookup	failures  from
	      the rrset	cache.

       flush_stats
	      Reset statistics to zero.

       flush_requestlist
	      Drop  the	 queries  that	are  worked  on.  Stops	working	on the
	      queries that the server is working on now.  The cache  is	 unaf-
	      fected.	No  reply  is  sent for	those queries, probably	making
	      those users request again	later.	 Useful	 to  make  the	server
	      restart  working	on queries with	new settings, such as a	higher
	      verbosity	level.

       dump_requestlist
	      Show what	is worked on.  Prints all queries that the  server  is
	      currently	 working  on.	Prints	the  time that users have been
	      waiting.	For internal requests, no time is printed.   And  then
	      prints  out the module status.  This prints the queries from the
	      first thread, and	not queries that are being serviced from other
	      threads.

       flush_infra all|IP
	      If all then entire infra cache is	emptied.  If a specific	IP ad-
	      dress, the entry for that	address	is removed from	the cache.  It
	      contains EDNS, ping and lameness data.

       dump_infra
	      Show the contents	of the infra cache.

       set_option opt: val
	      Set  the	option to the given value without a reload.  The cache
	      is therefore not flushed.	 The option must end with  a  ':'  and
	      whitespace  must be between the option and the value.  Some val-
	      ues may not have an effect if set	this way, the new  values  are
	      not  written  to the config file,	not all	options	are supported.
	      This is different	from the set_option call in libunbound,	 where
	      all values work because unbound has not been initialized.

	      The  values that work are: statistics-interval, statistics-cumu-
	      lative,	   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, iden-
	      tity, version, val-log-level,  val-log-squelch,  ignore-cd-flag,
	      add-holddown,  del-holddown, keep-missing, tcp-upstream, ssl-up-
	      stream, max-udp-size, ratelimit,	cache-max-ttl,	cache-min-ttl,
	      cache-max-negative-ttl.

       get_option opt
	      Get  the	value  of  the option.	Give the option	name without a
	      trailing ':'.  The value is printed.  If the value is "",	 noth-
	      ing  is printed and the connection closes.  On error 'error ...'
	      is printed (it gives a syntax error  on  unknown	option).   For
	      some  options  a	list  of values, one on	each line, is printed.
	      The options are shown from the  config  file  as	modified  with
	      set_option.   For	 some  options an override may have been taken
	      that does	not show up with this command, not results  from  e.g.
	      the  verbosity  and  forward  control commands.  Not all options
	      work,  see  list_stubs,  list_forwards,	list_local_zones   and
	      list_local_data for those.

       list_stubs
	      List the stub zones in use.  These are printed one by one	to the
	      output.  This includes the root hints in use.

       list_forwards
	      List the forward zones in	use.  These are	printed	zone  by  zone
	      to the output.

       list_insecure
	      List the zones with domain-insecure.

       list_local_zones
	      List  the	 local	zones  in use.	These are printed one per line
	      with zone	type.

       list_local_data
	      List the local data  RRs	in  use.   The	resource  records  are
	      printed.

       insecure_add zone
	      Add  a domain-insecure for the given zone, like the statement in
	      unbound.conf.  Adds to the running unbound without affecting the
	      cache  contents (which may still be bogus, use flush_zone	to re-
	      move it),	does not affect	the config file.

       insecure_remove zone
	      Removes domain-insecure for the given zone.

       forward_add [+i]	zone addr ...
	      Add a new	forward	zone to	running	unbound.  With +i option  also
	      adds  a  domain-insecure	for  the zone (so it can resolve inse-
	      curely if	you have a DNSSEC root	trust  anchor  configured  for
	      other  names).   The  addr  can be IP4, IP6 or nameserver	names,
	      like forward-zone	config in unbound.conf.

       forward_remove [+i] zone
	      Remove a forward zone from running unbound.  The +i also removes
	      a	domain-insecure	for the	zone.

       stub_add	[+ip] zone addr	...
	      Add  a  new  stub	 zone to running unbound.  With	+i option also
	      adds a domain-insecure 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 stub-zone config  in  un-
	      bound.conf.

       stub_remove [+i]	zone
	      Remove  a	stub zone from running unbound.	 The +i	also removes a
	      domain-insecure for the zone.

       forward [off | addr ... ]
	      Setup forwarding mode.  Configures  if  the  server  should  ask
	      other upstream nameservers, should go to the internet root name-
	      servers itself, or show the current config.  You could pass  the
	      nameservers after	a DHCP update.

	      Without  arguments the current list of addresses used to forward
	      all queries to is	printed.  On startup this  is  from  the  for-
	      ward-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	 name-
	      servers  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.

       ratelimit_list [+a]
	      List  the	 domains  that	are ratelimited.  Printed one per line
	      with current estimated qps and qps limit from config.   With  +a
	      it  prints  all  domains,	not just the ratelimited domains, with
	      their estimated qps.  The	ratelimited domains  return  an	 error
	      for uncached (new) queries, but cached queries work as normal.

EXIT CODE
       The  unbound-control  program  exits  with status code 1	on error, 0 on
       success.

SET UP
       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 config-
       ured 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  un-
       bound.conf.

STATISTIC COUNTERS
       The stats command shows a number	of statistic counters.

       threadX.num.queries
	      number of	queries	received by thread

       threadX.num.cachehits
	      number  of queries that were successfully	answered using a cache
	      lookup

       threadX.num.cachemiss
	      number of	queries	that needed recursive processing

       threadX.num.prefetch
	      number of	cache prefetches performed.  This number  is  included
	      in  cachehits, as	the original query had the unprefetched	answer
	      from cache, and resulted in recursive processing,	taking a  slot
	      in  the  requestlist.   Not part of the recursivereplies (or the
	      histogram	thereof) or cachemiss, as a cache response was sent.

       threadX.num.recursivereplies
	      The number of replies sent to queries that needed	recursive pro-
	      cessing.	Could  be smaller than threadX.num.cachemiss if	due to
	      timeouts no replies were sent for	some queries.

       threadX.requestlist.avg
	      The average number of requests in	the  internal  recursive  pro-
	      cessing  request list on insert of a new incoming	recursive pro-
	      cessing query.

       threadX.requestlist.max
	      Maximum size attained by the internal recursive  processing  re-
	      quest list.

       threadX.requestlist.overwritten
	      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.

       threadX.requestlist.exceeded
	      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.

       threadX.requestlist.current.all
	      Current  size of the request list, includes internally generated
	      queries (such as priming queries and glue	lookups).

       threadX.requestlist.current.user
	      Current size of the request list,	only the requests from	client
	      queries.

       threadX.recursion.time.avg
	      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.

       threadX.recursion.time.median
	      The median of the	time it	took to	answer queries that needed re-
	      cursive processing.  The median  means  that  50%	 of  the  user
	      queries  were  answered  in less than this time.	Because	of big
	      outliers (usually	queries	to non responsive servers), the	 aver-
	      age  can be bigger than the median.  This	median has been	calcu-
	      lated by interpolation from a histogram.

       threadX.tcpusage
	      The currently held tcp buffers for incoming connections.	A spot
	      value  on	 the  time of the request.  This helps you spot	if the
	      incoming-num-tcp buffers are full.

       total.num.queries
	      summed over threads.

       total.num.cachehits
	      summed over threads.

       total.num.cachemiss
	      summed over threads.

       total.num.prefetch
	      summed over threads.

       total.num.recursivereplies
	      summed over threads.

       total.requestlist.avg
	      averaged over threads.

       total.requestlist.max
	      the maximum of the thread	requestlist.max	values.

       total.requestlist.overwritten
	      summed over threads.

       total.requestlist.exceeded
	      summed over threads.

       total.requestlist.current.all
	      summed over threads.

       total.recursion.time.median
	      averaged over threads.

       total.tcpusage
	      summed over threads.

       time.now
	      current time in seconds since 1970.

       time.up
	      uptime since server boot in seconds.

       time.elapsed
	      time since last statistics printout, in seconds.

EXTENDED STATISTICS
       mem.total.sbrk
	      If sbrk(2) is available, an estimate of the  heap	 size  of  the
	      program  in  number  of bytes. Close to the total	memory used by
	      the program, as reported by top and ps.  Could be	wrong  if  the
	      OS allocates memory non-contiguously.

       mem.cache.rrset
	      Memory in	bytes in use by	the RRset cache.

       mem.cache.message
	      Memory in	bytes in use by	the message cache.

       mem.mod.iterator
	      Memory in	bytes in use by	the iterator module.

       mem.mod.validator
	      Memory in	bytes in use by	the validator module. Includes the key
	      cache and	negative cache.

       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.  Times larger  or  equal  to	 the  lowerbound,  and
	      smaller than the upper bound.  There are 40 buckets, with	bucket
	      sizes doubling.

       num.query.type.A
	      The total	number of queries over all threads with	query type  A.
	      Printed  for  the	 other	query  types as	well, but only for the
	      types for	which queries were received, thus =0 entries are omit-
	      ted for brevity.

       num.query.type.other
	      Number of	queries	with query types 256-65535.

       num.query.class.IN
	      The total	number of queries over all threads with	query class IN
	      (internet).  Also	printed	for other classes (such	as CH  (CHAOS)
	      sometimes	used for debugging), or	NONE, ANY, used	by dynamic up-
	      date.  num.query.class.other is printed for classes 256-65535.

       num.query.opcode.QUERY
	      The total	number of queries over all threads with	 query	opcode
	      QUERY.  Also printed for other opcodes, UPDATE, ...

       num.query.tcp
	      Number  of  queries that were made using TCP towards the unbound
	      server.

       num.query.tcpout
	      Number of	queries	that the unbound server	made using TCP	outgo-
	      ing towards other	servers.

       num.query.ipv6
	      Number  of queries that were made	using IPv6 towards the unbound
	      server.

       num.query.flags.RD
	      The number of queries that had the RD flag set  in  the  header.
	      Also  printed  for  flags	 QR, AA, TC, RA, Z, AD,	CD.  Note that
	      queries with flags QR, AA	or TC may have been  rejected  because
	      of that.

       num.query.edns.present
	      number of	queries	that had an EDNS OPT record present.

       num.query.edns.DO
	      number  of  queries  that	 had  an  EDNS	OPT record with	the DO
	      (DNSSEC OK) bit set.  These queries are  also  included  in  the
	      num.query.edns.present number.

       num.answer.rcode.NXDOMAIN
	      The  number of answers to	queries, from cache or from recursion,
	      that had the return code NXDOMAIN. Also printed  for  the	 other
	      return codes.

       num.answer.rcode.nodata
	      The number of answers to queries that had	the pseudo return code
	      nodata.  This means the actual return code was NOERROR, but  ad-
	      ditionally,  no  data  was carried in the	answer (making what is
	      called a NOERROR/NODATA answer).	These  queries	are  also  in-
	      cluded  in the num.answer.rcode.NOERROR number.  Common for AAAA
	      lookups when an A	record exists, and no AAAA.

       num.answer.secure
	      Number of	answers	that were secure.  The answer  validated  cor-
	      rectly.	The  AD	 bit  might have been set in some of these an-
	      swers, where the client signalled	(with DO  or  AD  bit  in  the
	      query) that they were ready to accept the	AD bit in the answer.

       num.answer.bogus
	      Number  of  answers  that	were bogus.  These answers resulted in
	      SERVFAIL to the client because the answer	failed validation.

       num.rrset.bogus
	      The number of rrsets marked bogus	by the	validator.   Increased
	      for every	RRset inspection that fails.

       unwanted.queries
	      Number  of  queries  that	 were  refused or dropped because they
	      failed the access	control	settings.

       unwanted.replies
	      Replies that were	unwanted or unsolicited.  Could	have been ran-
	      dom  traffic, delayed duplicates,	very late answers, or could be
	      spoofing attempts.  Some low level of late answers  and  delayed
	      duplicates  are to be expected with the UDP protocol.  Very high
	      values could indicate a threat (spoofing).

       msg.cache.count
	      The number of items (DNS replies)	in the message cache.

       rrset.cache.count
	      The number of RRsets in the rrset	cache.	This  includes	rrsets
	      used  by	the messages in	the message cache, but also delegation
	      information.

       infra.cache.count
	      The number of items in the infra cache.  These are IP  addresses
	      with their timing	and protocol support information.

       key.cache.count
	      The  number  of  items in	the key	cache.	These are DNSSEC keys,
	      one item per delegation point, and their validation status.

FILES
       /var/unbound/unbound.conf
	      unbound configuration file.

       /var/unbound
	      directory	with private keys (unbound_server.key and unbound_con-
	      trol.key)	 and  self-signed certificates (unbound_server.pem and
	      unbound_control.pem).

SEE ALSO
       unbound.conf(5),	unbound(8).

NLnet Labs			 Sep 27, 2016		    unbound-control(8)

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | EXIT CODE | SET UP | STATISTIC COUNTERS | EXTENDED STATISTICS | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=unbound-control&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help