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

FreeBSD Manual Pages


home | help
local-unbound-control(8)      local-unbound 1.9.2     local-unbound-control(8)

       local-unbound-control,  local-unbound-control-setup - Local-unbound re-
       mote server control utility.

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

       Local-unbound-control performs remote administration on	the  local-un-
       bound(8)	DNS server.  It	reads the configuration	file, contacts the lo-
       cal-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
	      config file /var/unbound/unbound.conf is used.

       -s server[@port]
	      the address is read from the config file.

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

       There are several commands that the server understands.

       start  Start  the server. Simply	execs local-unbound(8).	 The local-un-
	      bound executable is searched for in the PATH set in the environ-
	      ment.   It is started with the config file specified using -c or
	      the default config file.

       stop   Stop the server. The server daemon exits.

	      file fresh.

       verbosity number
	      Change  verbosity	 value	for  logging. Same values as verbosity
	      next verbosity control command.

	      Reopen the logfile, close	and open it.  Useful  for  logrotation
	      are using	syslog it will attempt to close	and  open  the	syslog
	      (which may not work if chrooted).

	      be controlled using the statistics-cumulative config  statement.

	      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
	      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-

       local_data RR data...
	      config statement,	except for when	no covering zone  exists.   In
	      that case	this remote control command creates a transparent zone
	      returning	detailed syntax	errors.

       local_data_remove name
	      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

	      Add  local zones read from stdin of local-unbound-control. Input
	      is read per line,	with name space	type on	a line.	For bulk addi-

	      Remove local zones read from stdin of local-unbound-control. In-
	      put is one name per line.	For bulk removals.

	      Add local	data RRs read from stdin of local-unbound-control. In-
	      put is one RR per	line. For bulk additions.

	      Remove  local data RRs read from stdin of	local-unbound-control.
	      Input is one name	per line. For bulk removals.


	      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
	      the name specified.

       flush name
	      to do. Other record types	can be	removed	 using	flush_type  or

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

       flush_zone name
	      rrsets and key entries are removed so that new lookups  will  be
	      is a slow	operation.  The	entries	are set	to expired in the  im-
	      plementation  of	this  command (so, with	serve-expired enabled,
	      it'll serve that information but schedule	a prefetch for new in-

	      Remove all bogus data from the cache.

	      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.

	      Reset statistics to zero.

	      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.

	      currently	 working  on.	Prints	the  time that users have been
	      prints  out the module status.  This prints the queries from the
	      first thread, and	not queries that are being serviced from other

       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.

	      Show the contents	of the infra cache.

       set_option opt: val
	      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
	      This is different	from the set_option call in libunbound,	 where
	      all values work because local-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,	 ip-ratelimit,	cache-max-ttl,
	      cache-min-ttl, cache-max-negative-ttl.

       get_option opt
	      trailing ':'.  The value is printed.  If the value is "",	 noth-
	      ing  is printed and the connection closes.  On error 'error ...'
	      The options are shown from the  config  file  as	modified  with
	      set_option.   For	 some  options an override may have been taken
	      the  verbosity  and  forward  control commands.  Not all options
	      work,  see  list_stubs,  list_forwards,	list_local_zones   and
	      list_local_data for those.

	      output.  This includes the root hints in use.

	      to the output.

	      List the zones with domain-insecure.

	      with zone	type.

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

       insecure_add zone
	      Add  a domain-insecure for the given zone, like the statement in
	      unbound.conf.  Adds to the running local-unbound without affect-
	      ing the cache contents (which may	still be bogus,	use flush_zone
	      to remove	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-

       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.

	      used to forward queries to.  The	addresses  must	 be  separated
	      (default port is 53 (DNS)).

	      By default the forwarder information from	the  config  file  for
	      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.

       ip_ratelimit_list [+a]
	      List  the	 ip  addresses	that are ratelimited.  Printed one per
	      line with	current	estimated qps and qps limit from config.  With
	      +a  it  prints all ips, not just the ratelimited ips, with their
	      estimated	qps.  The ratelimited ips are dropped before  checking
	      the cache.

	      List  the	 auth zones that are configured.  Printed one per line
	      with a status, indicating	if the zone is expired and current se-
	      rial number.

       auth_zone_reload	zone
	      Reload  the  auth	 zone  from zonefile.  The zonefile is read in
	      overwriting the current contents of the zone  in	memory.	  This
	      changes  the  auth zone contents itself, not the cache contents.
	      Such cache contents exists if you	set local-unbound to  validate
	      with  for-upstream  yes  and that	can be cleared with flush_zone

       auth_zone_transfer zone
	      Transfer the auth	zone from master.  The	auth  zone  probe  se-
	      quence  is  started, where the masters are probed	to see if they
	      have an updated zone (with the SOA serial	check).	 And then  the
	      zone is transferred for a	newer zone version.

       view_list_local_zones view
	      list_local_zones for given view.

       view_local_zone view name type
	      local_zone for given view.

       view_local_zone_remove view name
	      local_zone_remove	for given view.

       view_list_local_data view
	      list_local_data for given	view.

       view_local_data view RR data...
	      local_data for given view.

       view_local_data_remove view name
	      local_data_remove	for given view.

       view_local_datas	view
	      Add  a  list  of local_data for given view from stdin.  Like lo-

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

       the server and client.  The script  local-unbound-control-setup	gener-
       ates  these  in the default run directory, or with -d in	another	direc-
       tory.  If you change the	access control permissions on  the  key	 files
       you  can	decide who can use local-unbound-control, by default owner and
       have  configured	in unbound.conf	or as root, so that the	daemon is per-
       mitted to read the files, for example with:
	   sudo	-u local-unbound local-unbound-control-setup
       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-

       The stats command shows a number	of statistic counters.

	      number of	queries	received by thread

	      number of	queries	rate limited by	thread

	      number of	queries	that were successfully answered	using a	 cache

	      number of	queries	that needed recursive processing

	      number  of queries that were encrypted and successfully decapsu-
	      lated by dnscrypt.

	      number of	queries	that were requesting dnscrypt certificates.

	      number of	queries	received on dnscrypt port that were  cleartext
	      and not a	request	for certificates.

	      number  of  request  that	 were  neither	cleartext,  not	 valid
	      dnscrypt messages.

	      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

	      number of	replies	with ttl zero, because they served an  expired
	      cache entry.

	      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.

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

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

	      Number of	requests in the	request	list that were overwritten  by
	      recursive	processing and the server has a	hard time.

	      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.

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

	      Current  size of the request list, only the requests from	client

	      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.

	      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.

	      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.

	      summed over threads.

	      summed over threads.

	      summed over threads.

	      summed over threads.

	      summed over threads.

	      summed over threads.

	      summed over threads.

	      summed over threads.

	      summed over threads.

	      summed over threads.

	      averaged over threads.

	      the maximum of the thread	requestlist.max	values.

	      summed over threads.

	      summed over threads.

	      summed over threads.

	      averaged over threads.

	      summed over threads.
	      current time in seconds since 1970.

	      uptime since server boot in seconds.

	      time since last statistics printout, in seconds.

	      Memory in	bytes in use by	the RRset cache.

	      Memory in	bytes in use by	the message cache.

	      Memory in	bytes in use by	the dnscrypt shared secrets cache.

	      Memory in	bytes in use by	the dnscrypt nonce cache.

	      Memory in	bytes in use by	the iterator module.

	      cache and	negative cache.

	      Memory in	bytes in used by the TCP and TLS stream	wait  buffers.
	      These are	answers	waiting	to be written back to the clients.
	      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
	      sizes doubling.

	      types for	which queries were received, thus =0 entries are omit-
	      ted for brevity.

	      Number of	queries	with query types 256-65535.

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

	      The  total  number of queries over all threads with query	opcode

	      Number of	queries	that were made using TCP towards the local-un-
	      bound server.

	      Number  of  queries that the local-unbound server	made using TCP
	      outgoing towards other servers.

	      Number of	queries	that were made using TLS towards the local-un-
	      bound  server.  These are	also counted in	num.query.tcp, because
	      TLS uses TCP.

	      Number of	TLS session resumptions, these are  queries  over  TLS
	      towards  the  local-unbound server where the client negotiated a
	      TLS session resumption key.

	      Number of	queries	that were made using IPv6 towards  the	local-
	      unbound server.

	      of that.

	      number of	queries	that had an EDNS OPT record present.

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

	      The number of queries that are turned away from  being  send  to
	      nameserver due to	ratelimiting.

	      The number of dnscrypt queries that did not find a shared	secret
	      in the cache.  The can be	use to compute the shared  secret  hi-

	      The  number  of  dnscrypt	 queries that found a nonce hit	in the
	      nonce cache and hence are	considered a query replay.

	      that  had	 the  return code NXDOMAIN. Also printed for the other
	      return codes.

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

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

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

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

	      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).

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

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

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

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

	      The  number  of items in the shared secret cache.	These are pre-
	      computed shared secrets for a given client public	key/server se-
	      cret  key	 pair. Shared secrets are CPU intensive	and this cache
	      allows local-unbound to avoid recomputing	the shared secret when
	      multiple dnscrypt	queries	are sent from the same client.

	      The  number  of  items  in the client nonce cache. This cache is
	      used to prevent dnscrypt queries replay. The client  nonce  must
	      be  unique  for  each  client public key/server secret key pair.
	      This cache should	be able	to host	QPS * `replay window` interval
	      keys  to	prevent	 replay	of a query during `replay window` sec-

	      The number of queries answered  from  auth-zone  data,  upstream
	      queries.	 These	queries	 would	otherwise have been sent (with
	      fallback enabled)	to the internet, but are now answered from the
	      auth zone.

	      The  number  of  queries	for downstream answered	from auth-zone
	      data.  These queries are from downstream clients,	and  have  had
	      an answer	from the data in the auth zone.

	      The  number  of  queries answered	using cached NSEC records with
	      NODATA RCODE.  These queries would otherwise have	been  sent  to
	      the internet, but	are now	answered using cached data.

	      The  number  of  queries answered	using cached NSEC records with
	      NXDOMAIN RCODE.  These queries would otherwise have been sent to
	      the internet, but	are now	answered using cached data.

	      Number  of queries that got an answer that contained EDNS	client
	      subnet data.

	      Number of	queries	answered from the edns	client	subnet	cache.
	      These are	counted	as cachemiss by	the main counters, but hit the
	      client subnet specific cache, after  getting  processed  by  the
	      edns client subnet module.

	      local-unbound configuration file.

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

       unbound.conf(5),	local-unbound(8).

NLnet Labs			 Jun 17, 2019	      local-unbound-control(8)


Want to link to this manual page? Use this URL:

home | help