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

FreeBSD Manual Pages

  
 
  

home | help
REC_CONTROL(1)		       PowerDNS	Recursor		REC_CONTROL(1)

NAME
       rec_control - Command line tool to control a running Recursor

SYNOPSIS
       rec_control [OPTION]... COMMAND [COMMAND-OPTION]...

DESCRIPTION
       rec_control allows the operator to query	and control a running instance
       of the PowerDNS Recursor.

       rec_control talks to the	recursor via a the 'controlsocket'.  Which  is
       usually	located	in /var/run . The --socket-dir or the --config-dir and
       --config-name switches control to which process rec_control connects.

EXAMPLES
       To see if the Recursor is alive,	run:

	  # rec_control	ping

       To stop the recursor by hand, run:

	  # rec_control	quit

       To dump the cache to disk, execute:

	  # rec_control	dump-cache /tmp/the-cache

OPTIONS
       --help provide this helpful message.

       --config-dir=_path_
	      Directory	where the recursor.conf	lives.

       --config-name=_name_
	      Name of the virtual configuration.

       --socket-dir=_path_
	      Where the	controlsocket will live, please	use  --config-dir  in-
	      stead.

       --socket-pid=_pid_
	      When running in SMP mode,	pid of pdns_recursor to	control.

       --timeout=_num_
	      Number  of  seconds  to wait for the remote PowerDNS Recursor to
	      respond.

COMMANDS
       add-dont-throttle-names NAME [NAME...]
	      Add names	for nameserver domains that may	not be throttled.

       add-dont-throttle-netmasks NETMASK [NETMASK...]
	      Add netmasks for nameservers that	may not	be throttled.

       add-nta DOMAIN [REASON]
	      Add a Negative Trust Anchor for DOMAIN, suffixed optionally with
	      REASON.

       add-ta DOMAIN DSRECORD
	      Add a Trust Anchor for DOMAIN with DS record data	DSRECORD. This
	      adds the new Trust Anchor	to the existing	set of	Trust  Anchors
	      for DOMAIN.

       current-queries
	      Shows the	currently active queries.

       clear-dont-throttle-names NAME [NAME...]
	      Remove  names  that  are not allowed to be throttled. If NAME is
	      '*', remove all

       clear-dont-throttle-netmasks NETMASK [NETMASK...]
	      Remove netmasks that are not allowed to be throttled. If NETMASK
	      is '*', remove all

       clear-nta DOMAIN...
	      Remove Negative Trust Anchor for one or more DOMAINs. Set	domain
	      to '*' to	remove all NTA's.

       clear-ta	[DOMAIN]...
	      Remove Trust Anchor for one or more DOMAINs. Note	that  removing
	      the root trust anchor is not possible.

       dump-cache FILENAME
	      Dumps  the  entire cache to FILENAME. This file should not exist
	      already, PowerDNS	will refuse to overwrite  it.  While  dumping,
	      the recursor will	not answer questions.

	      Typical  PowerDNS	 Recursors  run	 multiple  threads,  therefore
	      you'll see duplicate, different entries for  the	same  domains.
	      The  negative  cache  is	also  dumped  to  the  same  file. The
	      per-thread positive and negative cache dumps are separated  with
	      an appropriate comment.

	      NOTE:
		 pdns_recursor	often  runs  in	a chroot. You can retrieve the
		 file using:

		     rec_control dump-cache /tmp/file
		     mv	/proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename

       dump-edns FILENAME
	      Dumps the	EDNS status  to	 the  filename	mentioned.  This  file
	      should  not exist	already, PowerDNS will refuse to overwrite it.
	      While dumping, the recursor will not answer questions.

	      NOTE:
		 pdns_recursor often runs in a chroot. You  can	 retrieve  the
		 file using:

		     rec_control dump-edns /tmp/file
		     mv	/proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename

       dump-nsspeeds FILENAME
	      Dumps the	nameserver speed statistics to the FILENAME mentioned.
	      This file	should not exist  already,  PowerDNS  will  refuse  to
	      overwrite	 it. While dumping, the	recursor will not answer ques-
	      tions. Statistics	are kept per thread, and the dumps end	up  in
	      the same file.

	      NOTE:
		 pdns_recursor	often  runs  in	a chroot. You can retrieve the
		 file using:

		     rec_control dump-nsspeeds /tmp/file
		     mv	/proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename

       dump-rpz	ZONE NAME FILE NAME
	      Dumps the	content	of the RPZ zone	named ZONE NAME	to  the	 FILE-
	      NAME  mentioned.	This  file  should not exist already, PowerDNS
	      will refuse to overwrite it otherwise. While dumping, the	recur-
	      sor will not answer questions.

	      NOTE:
		 pdns_recursor	often  runs  in	a chroot. You can retrieve the
		 file using:

		     rec_control dump-rpz ZONE_NAME /tmp/file
		     mv	/proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename

       dump-throttlemap	FILENAME
	      Dump the contents	of the throttle	map to the FILENAME mentioned.
	      This  file  should  not  exist  already, PowerDNS	will refuse to
	      overwrite	it otherwise. While dumping, the recursor will not an-
	      swer questions.

	      NOTE:
		 pdns_recursor	often  runs  in	a chroot. You can retrieve the
		 file using:

		     rec_control dump-throttlemap /tmp/file
		     mv	/proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename

       dump-failedservers FILENAME
	      Dump the contents	of the failed server map to the	FILENAME  men-
	      tioned.	This  file  should  not	 exist	already, PowerDNS will
	      refuse to	overwrite it otherwise.	While  dumping,	 the  recursor
	      will not answer questions.

	      NOTE:
		 pdns_recursor	often  runs  in	a chroot. You can retrieve the
		 file using:

		     rec_control dump-failedservers /tmp/file
		     mv	/proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename

       get STATISTIC [STATISTIC]...
	      Retrieve a statistic. For	items that can be queried, see ../met-
	      rics

       get-all
	      Retrieve all known statistics.

       get-dont-throttle-names
	      Get the list of names that are not allowed to be throttled.

       get-dont-throttle-netmasks
	      Get the list of netmasks that are	not allowed to be throttled.

       get-ntas
	      Get a list of the	currently configured Negative Trust Anchors.

       get-tas
	      Get a list of the	currently configured Trust Anchors.

       get-parameter KEY [KEY]...
	      Retrieves	the specified configuration parameter(s).

       get-qtypelist
	      Retrieves	 QType	statistics.  Queries  from  cache aren't being
	      counted yet.

       help   Shows a list of supported	commands  understood  by  the  running
	      pdns_recursor

       ping   Check if server is alive.

       quit   Request shutdown of the recursor,	exiting	the process while let-
	      ting the OS clean	up resources.

       quit-nicely
	      Request nice shutdown of the recursor. This  method  allows  all
	      threads  to finish their current work and	releases resources be-
	      fore exiting. This is the	preferred method to stop the recursor.

       reload-acls
	      Reloads ACLs.

       reload-lua-script [FILENAME]
	      (Re)loads	Lua script FILENAME. If	FILENAME is empty, attempt  to
	      reload  the  currently  loaded  script. This replaces the	script
	      currently	loaded.

       reload-lua-config [FILENAME]
	      (Re)loads	Lua configuration FILENAME. If FILENAME	is empty,  at-
	      tempt  to	 reload	 the currently loaded file. Note that FILENAME
	      will be fully executed, any settings changed at runtime that are
	      not  modified in this file, will still be	active.	Reloading RPZ,
	      especially by AXFR, can take some	time; during which the	recur-
	      sor will not answer questions.

       reload-zones
	      Reload authoritative and forward zones. Retains current configu-
	      ration in	case of	errors.

       set-carbon-server CARBON	SERVER [CARBON OURNAME]
	      Set the carbon-server setting to CARBON SERVER. If  CARBON  OUR-
	      NAME is not empty, also set the carbon-ourname setting to	CARBON
	      OURNAME.

       set-dnssec-log-bogus SETTING
	      Set dnssec-log-bogus setting to SETTING. Set to 'on' or 'yes' to
	      log  DNSSEC  validation failures and to 'no' or 'off' to disable
	      logging these failures.

       set-ecs-minimum-ttl NUM
	      Set ecs-minimum-ttl-override to NUM.

       set-max-cache-entries NUM
	      Change the maximum number	of entries in the DNS cache.   If  re-
	      duced,  the  cache  size	will start shrinking to	this number as
	      part of the normal cache purging process,	 which	might  take  a
	      while.

       set-max-packetcache-entries NUM
	      Change  the  maximum  number of entries in the packet cache.  If
	      reduced, the cache size will start shrinking to this  number  as
	      part  of	the  normal  cache purging process, which might	take a
	      while.

       set-minimum-ttl NUM
	      Set minimum-ttl-override to NUM.

       top-queries
	      Shows  the  top-20  queries.  Statistics	are  over   the	  last
	      'stats-ringbuffer-entries' queries.

       top-pub-queries
	      Shows  the top-20	queries	grouped	by public suffix list. Statis-
	      tics are over the	last 'stats-ringbuffer-entries'	queries.

       top-largeanswer-remotes
	      Shows the	top-20 remote hosts causing large answers.  Statistics
	      are over the last	'stats-ringbuffer-entries' queries.

       top-remotes
	      Shows  the  top-20 most active remote hosts. Statistics are over
	      the last 'stats-ringbuffer-entries' queries.

       top-servfail-queries
	      Shows the	top-20 queries causing servfail	responses.  Statistics
	      are over the last	'stats-ringbuffer-entries' queries.

       top-bogus-queries
	      Shows the	top-20 queries causing bogus responses.	Statistics are
	      over the last 'stats-ringbuffer-entries' queries.

       top-pub-servfail-queries
	      Shows the	top-20 queries causing servfail	responses  grouped  by
	      public  suffix  list.  Statistics	are over the last 'stats-ring-
	      buffer-entries' queries.

       top-pub-bogus-queries
	      Shows the	top-20 queries causing bogus responses grouped by pub-
	      lic  suffix  list.  Statistics  are  over	 the last 'stats-ring-
	      buffer-entries' queries.

       top-servfail-remotes
	      Shows the	top-20 most active remote hosts	causing	 servfail  re-
	      sponses.	 Statistics  are  over	the last 'stats-ringbuffer-en-
	      tries' queries.

       top-bogus-remotes
	      Shows the	top-20 most active  remote  hosts  causing  bogus  re-
	      sponses.	 Statistics  are  over	the last 'stats-ringbuffer-en-
	      tries' queries.

       top-timeouts
	      Shows the	top-20 most active  downstream	timeout	 destinations.
	      Statistics are over the last 'stats-ringbuffer-entries' queries.

       trace-regex REGEX
	      Emit  resolution trace for matching queries. Empty regex to dis-
	      able trace.

	      Queries matching this regular expression will  generate  volumi-
	      nous tracing output. Be aware that matches from the packet cache
	      will still not  generate	tracing.  To  unset  the  regex,  pass
	      trace-regex without a new	regex.

	      The  regular expression is matched against domain	queries	termi-
	      nated with a dot.	For example the	regex 'powerdns.com$' will not
	      match  a query for 'www.powerdns.com', since the attempted match
	      will be with 'www.powerdns.com.'.

	      In addition, since this is a regular expression, to  exclusively
	      match  queries  for  'www.powerdns.com',	one  should escape the
	      dots: '^www\.powerdns\.com\.$'.  Note  that  the	single	quotes
	      prevent further interpretation of	the backslashes	by the shell.

	      Multiple	matches	 can be	chained	with the | operator. For exam-
	      ple, to match all	queries	for Dutch (.nl)	and German  (.de)  do-
	      main names, use: '\.nl\.$|\.de\.$'.

       unload-lua-script
	      Unloads Lua script if one	was loaded.

       version
	      Report running version.

       wipe-cache DOMAIN [DOMAIN] [...]
	      Wipe  entries for	DOMAIN (exact name match) from the cache. This
	      is useful	if, for	example, an important server has a new IP  ad-
	      dress,  but  the	TTL has	not yet	expired. Multiple domain names
	      can be passed.  DOMAIN can be suffixed with a '$'. to delete the
	      whole  tree from the cache. i.e. 'powerdns.com$' will remove all
	      cached entries under and including the powerdns.com name.

	      Note: this command also wipes the	negative cache.

	      Warning: Don't just wipe "www.somedomain.com", its NS records or
	      CNAME target may still be	undesired, so wipe "somedomain.com" as
	      well.

       wipe-cache-typed	qtype DOMAIN [DOMAIN] [...]
	      Same as wipe-cache, but only wipe	records	of type	qtype.

SEE ALSO
       pdns_recursor(1)

AUTHOR
       PowerDNS.COM BV

COPYRIGHT
       2001-2019, PowerDNS.COM BV

				 Dec 11, 2020			REC_CONTROL(1)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | OPTIONS | COMMANDS | SEE ALSO | AUTHOR | COPYRIGHT

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

home | help