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

FreeBSD Manual Pages

  
 
  

home | help
RNDC(8)				    BIND 9			       RNDC(8)

NAME
       rndc - name server control utility

SYNOPSIS
       rndc [-b	source-address]	[-c config-file] [-k key-file] [-s server] [-p
       port] [-q] [-r] [-V] [-y	key_id]	[[-4] |	[-6]] {command}

DESCRIPTION
       rndc controls the operation of a	name server;  it  supersedes  the  ndc
       utility.	 If rndc is invoked with no command line options or arguments,
       it prints a short summary of the	supported commands and	the  available
       options and their arguments.

       rndc  communicates  with	the name server	over a TCP connection, sending
       commands	authenticated with digital signatures. In the current versions
       of  rndc	 and  named,  the only supported authentication	algorithms are
       HMAC-MD5	(for compatibility), HMAC-SHA1,	HMAC-SHA224, HMAC-SHA256  (de-
       fault),	HMAC-SHA384, and HMAC-SHA512. They use a shared	secret on each
       end of the connection, which provides TSIG-style	authentication for the
       command request and the name server's response.	All commands sent over
       the channel must	be signed by a key_id known to the server.

       rndc reads a configuration file to determine how	to  contact  the  name
       server and decide what algorithm	and key	it should use.

OPTIONS
       -4     This option indicates use	of IPv4	only.

       -6     This option indicates use	of IPv6	only.

       -b source-address
	      This  option  indicates source-address as	the source address for
	      the connection to	the server. Multiple instances are  permitted,
	      to allow setting of both the IPv4	and IPv6 source	addresses.

       -c config-file
	      This  option indicates config-file as the	configuration file in-
	      stead of the default, /usr/local/etc/namedb/rndc.conf.

       -k key-file
	      This option indicates key-file as	the key	file  instead  of  the
	      default,	/etc/rndc.key. The key in /etc/rndc.key	is used	to au-
	      thenticate commands sent to the server if	the  config-file  does
	      not exist.

       -s server
	      server  is  the  name  or	 address of the	server which matches a
	      server statement in the  configuration  file  for	 rndc.	If  no
	      server  is  supplied  on the command line, the host named	by the
	      default-server clause in the options statement of	the rndc  con-
	      figuration file is used.

       -p port
	      This  option  instructs BIND 9 to	send commands to TCP port port
	      instead of its default control channel port, 953.

       -q     This option sets quiet mode, where message text returned by  the
	      server is	not printed unless there is an error.

       -r     This  option instructs rndc to print the result code returned by
	      named after executing the	requested  command  (e.g.,  ISC_R_SUC-
	      CESS, ISC_R_FAILURE, etc.).

       -V     This option enables verbose logging.

       -y key_id
	      This  option indicates use of the	key key_id from	the configura-
	      tion file. For control message  validation  to  succeed,	key_id
	      must  be	known  by  named  with	the  same algorithm and	secret
	      string. If no key_id is specified, rndc first looks  for	a  key
	      clause  in  the server statement of the server being used, or if
	      no server	statement is present for that host, then  in  the  de-
	      fault-key	clause of the options statement. Note that the config-
	      uration file contains shared secrets which are used to send  au-
	      thenticated  control commands to name servers, and should	there-
	      fore not have general read or write access.

COMMANDS
       A list of commands supported by rndc can	be seen	by running rndc	 with-
       out arguments.

       Currently supported commands are:

       addzone zone [class [view]] configuration
	      This  command adds a zone	while the server is running. This com-
	      mand requires the	allow-new-zones	option to be set to  yes.  The
	      configuration  string  specified on the command line is the zone
	      configuration  text  that	 would	 ordinarily   be   placed   in
	      named.conf.

	      The configuration	is saved in a file called viewname.nzf (or, if
	      named is compiled	with liblmdb, an  LMDB	database  file	called
	      viewname.nzd). viewname is the name of the view, unless the view
	      name contains characters that are	incompatible  with  use	 as  a
	      file  name,  in which case a cryptographic hash of the view name
	      is used instead. When named is restarted,	 the  file  is	loaded
	      into  the	 view  configuration so	that zones that	were added can
	      persist after a restart.

	      This sample addzone command adds the zone	example.com to the de-
	      fault view:

	      rndc  addzone example.com	'{ type	master;	file "example.com.db";
	      };'

	      (Note the	brackets around	and semi-colon after the zone configu-
	      ration text.)

	      See also rndc delzone and	rndc modzone.

       delzone [-clean]	zone [class [view]]
	      This command deletes a zone while	the server is running.

	      If the -clean argument is	specified, the zone's master file (and
	      journal file, if any) are	deleted	along with the	zone.  Without
	      the  -clean option, zone files must be deleted manually. (If the
	      zone is of type secondary	or stub, the files needing to  be  re-
	      moved are	reported in the	output of the rndc delzone command.)

	      If  the  zone  was originally added via rndc addzone, then it is
	      removed permanently. However, if it was originally configured in
	      named.conf,  then	 that original configuration remains in	place;
	      when the server is restarted or reconfigured, the	zone is	recre-
	      ated.  To	 remove	 it  permanently, it must also be removed from
	      named.conf.

	      See also rndc addzone and	rndc modzone.

       dnssec (	-status	| -rollover -key id [-alg algorithm]  [-when  time]  |
       -checkds	 [-key	id  [-alg algorithm]] [-when time] ( published | with-
       drawn ))	zone [class [view]]
	      This command allows you to interact with the "dnssec-policy"  of
	      a	given zone.

	      rndc dnssec -status show the DNSSEC signing state	for the	speci-
	      fied zone.

	      rndc dnssec -rollover allows you to schedule key rollover	for  a
	      specific key (overriding the original key	lifetime).

	      rndc  dnssec  -checkds  will  let	named know that	the DS for the
	      given key	has been seen published	into  or  withdrawn  from  the
	      parent.	This  is required in order to complete a KSK rollover.
	      If the -key id argument is specified, look for the key with  the
	      given identifier,	otherwise if there is only one key acting as a
	      KSK in the zone, assume the DS of	that key (if there are	multi-
	      ple  keys	 with  the  same tag, use -alg algorithm to select the
	      correct algorithm).  The time that the DS	has been published  or
	      withdrawn	is set to now, unless otherwise	specified with the ar-
	      gument -when time.

       dnstap (	-reopen	| -roll	[number] )
	      This command closes  and	re-opens  DNSTAP  output  files.  rndc
	      dnstap  -reopen allows the output	file to	be renamed externally,
	      so that named can	truncate and re-open  it.  rndc	 dnstap	 -roll
	      causes  the  output  file	to be rolled automatically, similar to
	      log files. The most recent output	file has ".0" appended to  its
	      name; the	previous most recent output file is moved to ".1", and
	      so on. If	number is specified, then the  number  of  backup  log
	      files is limited to that number.

       dumpdb  [-all | -cache |	-zones | -adb |	-bad | -expired	| -fail] [view
       ...]
	      This command dumps the server's caches (default) and/or zones to
	      the  dump	file for the specified views. If no view is specified,
	      all views	are dumped.  (See the dump-file	option in the  BIND  9
	      Administrator Reference Manual.)

       flush  This command flushes the server's	cache.

       flushname name [view]
	      This  command  flushes  the given	name from the view's DNS cache
	      and, if applicable, from the view's nameserver address database,
	      bad server cache,	and SERVFAIL cache.

       flushtree name [view]
	      This  command flushes the	given name, and	all of its subdomains,
	      from the view's DNS cache, address database, bad	server	cache,
	      and SERVFAIL cache.

       freeze [zone [class [view]]]
	      This  command  suspends updates to a dynamic zone. If no zone is
	      specified, then all zones	are suspended. This allows manual  ed-
	      its to be	made to	a zone normally	updated	by dynamic update, and
	      causes changes in	the journal file to be synced into the	master
	      file.  All dynamic update	attempts are refused while the zone is
	      frozen.

	      See also rndc thaw.

       halt [-p]
	      This command stops the server immediately. Recent	 changes  made
	      through  dynamic	update	or  IXFR  are  not saved to the	master
	      files, but are rolled forward from the journal  files  when  the
	      server  is  restarted. If	-p is specified, named's process ID is
	      returned.	This allows an	external  process  to  determine  when
	      named has	completed halting.

	      See also rndc stop.

       loadkeys	[zone [class [view]]]
	      This command fetches all DNSSEC keys for the given zone from the
	      key directory. If	they are within	their publication period, they
	      are  merged into the zone's DNSKEY RRset.	Unlike rndc sign, how-
	      ever, the	zone is	not immediately	re-signed by the new keys, but
	      is allowed to incrementally re-sign over time.

	      This  command  requires  that  the  zone	be  configured	with a
	      dnssec-policy, or	that the auto-dnssec zone  option  be  set  to
	      maintain,	 and  also requires the	zone to	be configured to allow
	      dynamic DNS. (See	"Dynamic Update	Policies" in the Administrator
	      Reference	Manual for more	details.)

       managed-keys (status | refresh |	sync | destroy)	[class [view]]
	      This  command  inspects and controls the "managed-keys" database
	      which handles RFC	5011 DNSSEC trust  anchor  maintenance.	 If  a
	      view is specified, these commands	are applied to that view; oth-
	      erwise, they are applied to all views.

	      o	When run with the status keyword, this prints the current sta-
		tus of the managed-keys	database.

	      o	When  run  with	 the refresh keyword, this forces an immediate
		refresh	query to be sent for all the  managed  keys,  updating
		the  managed-keys  database if any new keys are	found, without
		waiting	the normal refresh interval.

	      o	When run with the sync keyword,	this forces an immediate  dump
		of  the	 managed-keys  database	 to  disk  (in	the  file man-
		aged-keys.bind	or  (viewname.mkeys).  This  synchronizes  the
		database with its journal file,	so that	the database's current
		contents can be	inspected visually.

	      o	When run with the destroy keyword, the	managed-keys  database
		is  shut  down	and deleted, and all key maintenance is	termi-
		nated.	This command should be used only with extreme caution.

		Existing keys that are already trusted are  not	 deleted  from
		memory;	 DNSSEC	 validation can	continue after this command is
		used.  However,	key maintenance	operations cease  until	 named
		is restarted or	reconfigured, and all existing key maintenance
		states are deleted.

		Running	rndc reconfig or restarting  named  immediately	 after
		this  command  causes key maintenance to be reinitialized from
		scratch, just as if the	server	were  being  started  for  the
		first time. This is primarily intended for testing, but	it may
		also be	used, for example, to jumpstart	the acquisition	of new
		keys  in  the  event  of  a  trust  anchor  rollover,  or as a
		brute-force repair for key maintenance problems.

       modzone zone [class [view]] configuration
	      This command modifies the	configuration  of  a  zone  while  the
	      server is	running. This command requires the allow-new-zones op-
	      tion to be set to	 yes.	As  with  addzone,  the	 configuration
	      string  specified	 on the	command	line is	the zone configuration
	      text that	would ordinarily be placed in named.conf.

	      If the zone was originally added via rndc	addzone, the  configu-
	      ration  changes are recorded permanently and are still in	effect
	      after the	server is restarted or reconfigured.  However,	if  it
	      was originally configured	in named.conf, then that original con-
	      figuration remains in place; when	the server is restarted	or re-
	      configured,  the	zone reverts to	its original configuration. To
	      make  the	 changes  permanent,  it  must	also  be  modified  in
	      named.conf.

	      See also rndc addzone and	rndc delzone.

       notify zone [class [view]]
	      This command resends NOTIFY messages for the zone.

       notrace
	      This command sets	the server's debugging level to	0.

	      See also rndc trace.

       nta  [(	-class class | -dump | -force |	-remove	| -lifetime duration)]
       domain [view]
	      This command sets	a DNSSEC negative trust	anchor (NTA)  for  do-
	      main,  with a lifetime of	duration. The default lifetime is con-
	      figured in named.conf via	the nta-lifetime option, and  defaults
	      to one hour. The lifetime	cannot exceed one week.

	      A	 negative  trust anchor	selectively disables DNSSEC validation
	      for zones	that are known to be failing because of	 misconfigura-
	      tion  rather  than an attack. When data to be validated is at or
	      below an active NTA (and above any other	configured  trust  an-
	      chors),  named  aborts  the DNSSEC validation process and	treats
	      the data as insecure rather than bogus. This continues until the
	      NTA's lifetime has elapsed.

	      NTAs persist across restarts of the named	server.	The NTAs for a
	      view are saved in	a file called name.nta,	where name is the name
	      of  the  view;  if  it contains characters that are incompatible
	      with use as a file name, a cryptographic hash is generated  from
	      the name of the view.

	      An existing NTA can be removed by	using the -remove option.

	      An  NTA's	 lifetime  can be specified with the -lifetime option.
	      TTL-style	suffixes can be	used to	specify	the lifetime  in  sec-
	      onds,  minutes,  or  hours. If the specified NTA already exists,
	      its lifetime is updated to the new value.	 Setting  lifetime  to
	      zero is equivalent to -remove.

	      If  -dump	is used, any other arguments are ignored and a list of
	      existing NTAs is printed.	Note that this may include  NTAs  that
	      are expired but have not yet been	cleaned	up.

	      Normally,	 named periodically tests to see whether data below an
	      NTA can now be validated (see the	nta-recheck option in the  Ad-
	      ministrator  Reference Manual for	details). If data can be vali-
	      dated, then the NTA is regarded as no longer  necessary  and  is
	      allowed to expire	early. The -force parameter overrides this be-
	      havior and forces	an NTA to persist for its entire lifetime, re-
	      gardless	of whether data	could be validated if the NTA were not
	      present.

	      The view class can be specified  with  -class.  The  default  is
	      class  IN, which is the only class for which DNSSEC is currently
	      supported.

	      All of these options can be shortened, i.e., to -l, -r, -d,  -f,
	      and -c.

	      Unrecognized options are treated as errors. To refer to a	domain
	      or view name that	begins with a hyphen, use a double-hyphen (--)
	      on the command line to indicate the end of options.

       querylog	[(on | off)]
	      This  command  enables  or  disables query logging. For backward
	      compatibility, this command can also be used without an argument
	      to toggle	query logging on and off.

	      Query  logging  can  also	be enabled by explicitly directing the
	      queries  category	 to  a	channel	 in  the  logging  section  of
	      named.conf,  or  by specifying querylog yes; in the options sec-
	      tion of named.conf.

       reconfig
	      This command reloads the configuration file and loads new	zones,
	      but  does	 not  reload  existing	zone  files  even if they have
	      changed. This is faster than a full reload when there is a large
	      number of	zones, because it avoids the need to examine the modi-
	      fication times of	the zone files.

       recursing
	      This command dumps the list of queries named  is	currently  re-
	      cursing  on,  and	the list of domains to which iterative queries
	      are currently being sent.	 The second list includes  the	number
	      of  fetches  currently active for	the given domain, and how many
	      have been	passed or dropped because of the fetches-per-zone  op-
	      tion.

       refresh zone [class [view]]
	      This command schedules zone maintenance for the given zone.

       reload This command reloads the configuration file and zones.

       reload zone [class [view]]
	      This command reloads the given zone.

       retransfer zone [class [view]]
	      This  command retransfers	the given secondary zone from the pri-
	      mary server.

	      If the zone is configured	to use inline-signing, the signed ver-
	      sion  of	the zone is discarded; after the retransfer of the un-
	      signed version is	complete, the signed  version  is  regenerated
	      with new signatures.

       scan   This  command scans the list of available	network	interfaces for
	      changes, without performing a full reconfig or waiting  for  the
	      interface-interval timer.

       secroots	[-] [view ...]
	      This  command dumps the security roots (i.e., trust anchors con-
	      figured via trust-anchors, or the	managed-keys  or  trusted-keys
	      statements  [both	 deprecated],  or  dnssec-validation auto) and
	      negative trust anchors for the specified views. If  no  view  is
	      specified, all views are dumped. Security	roots indicate whether
	      they are configured as trusted keys, managed keys, or initializ-
	      ing managed keys (managed	keys that have not yet been updated by
	      a	successful key refresh query).

	      If the first argument is -, then the output is returned via  the
	      rndc  response channel and printed to the	standard output.  Oth-
	      erwise, it is written to the secroots dump file, which  defaults
	      to  named.secroots,  but can be overridden via the secroots-file
	      option in	named.conf.

	      See also rndc managed-keys.

       serve-stale (on | off | reset | status) [class [view]]
	      This command enables, disables, resets, or reports  the  current
	      status  of  the  serving	of  stale  answers  as	configured  in
	      named.conf.

	      If serving of stale answers is disabled by rndc-serve-stale off,
	      then  it remains disabled	even if	named is reloaded or reconfig-
	      ured. rndc serve-stale reset restores the	setting	as  configured
	      in named.conf.

	      rndc serve-stale status reports whether serving of stale answers
	      is currently enabled, disabled by	the configuration, or disabled
	      by  rndc.	 It  also  reports  the	values of stale-answer-ttl and
	      max-stale-ttl.

       showzone	zone [class [view]]
	      This command prints the configuration of a running zone.

	      See also rndc zonestatus.

       sign zone [class	[view]]
	      This command fetches all DNSSEC keys for the given zone from the
	      key directory (see the key-directory option in the BIND 9	Admin-
	      istrator Reference Manual). If they are within their publication
	      period,  they  are  merged  into the zone's DNSKEY RRset.	If the
	      DNSKEY  RRset  is	 changed,  then	 the  zone  is	 automatically
	      re-signed	with the new key set.

	      This  command  requires  that  the  zone	be  configured	with a
	      dnssec-policy, or	that the auto-dnssec zone option be set	to al-
	      low  or maintain,	and also requires the zone to be configured to
	      allow dynamic DNS. (See "Dynamic Update Policies"	in the BIND  9
	      Administrator Reference Manual for more details.)

	      See also rndc loadkeys.

       signing	[(-list	 | -clear keyid/algorithm | -clear all | -nsec3param (
       parameters | none ) | -serial value ) zone [class [view]]
	      This command lists, edits, or removes the	 DNSSEC	 signing-state
	      records for the specified	zone. The status of ongoing DNSSEC op-
	      erations,	such as	signing	or generating NSEC3 chains, is	stored
	      in  the  zone  in	 the  form  of	DNS  resource  records of type
	      sig-signing-type.	 rndc signing  -list  converts	these  records
	      into  a human-readable form, indicating which keys are currently
	      signing or have finished	signing	 the  zone,  and  which	 NSEC3
	      chains are being created or removed.

	      rndc  signing  -clear  can remove	a single key (specified	in the
	      same format that rndc signing -list uses to display it), or  all
	      keys.  In	 either	 case,	only  completed	 keys are removed; any
	      record indicating	that a key has not yet	finished  signing  the
	      zone is retained.

	      rndc  signing  -nsec3param sets the NSEC3	parameters for a zone.
	      This is the only supported mechanism for using  NSEC3  with  in-
	      line-signing  zones. Parameters are specified in the same	format
	      as an NSEC3PARAM resource	record:	hash algorithm,	flags,	itera-
	      tions, and salt, in that order.

	      Currently,  the only defined value for hash algorithm is 1, rep-
	      resenting	SHA-1. The flags may be	set to 0 or  1,	 depending  on
	      whether the opt-out bit in the NSEC3 chain should	be set.	itera-
	      tions defines the	number of additional times to apply the	 algo-
	      rithm  when  generating  an  NSEC3 hash. The salt	is a string of
	      data expressed in	hexadecimal, a hyphen (-') if no salt is to be
	      used,  or	 the keyword ``auto`, which causes named to generate a
	      random 64-bit salt.

	      So, for example, to create an NSEC3 chain	using the  SHA-1  hash
	      algorithm,  no  opt-out flag, 10 iterations, and a salt value of
	      "FFFF", use: rndc	signing	-nsec3param 1 0	10 FFFF	zone.  To  set
	      the  opt-out flag, 15 iterations,	and no salt, use: rndc signing
	      -nsec3param 1 1 15 - zone.

	      rndc signing -nsec3param none removes an	existing  NSEC3	 chain
	      and replaces it with NSEC.

	      rndc signing -serial value sets the serial number	of the zone to
	      value. If	the value would	cause the serial number	 to  go	 back-
	      wards,  it  is rejected. The primary use of this parameter is to
	      set the serial number on inline signed zones.

       stats  This command writes server statistics to	the  statistics	 file.
	      (See the statistics-file option in the BIND 9 Administrator Ref-
	      erence Manual.)

       status This command displays the	status of the server.  Note  that  the
	      number  of  zones	includes the internal bind/CH zone and the de-
	      fault ./IN hint zone, if there is	no explicit root zone  config-
	      ured.

       stop -p
	      This  command  stops  the	server,	making sure any	recent changes
	      made through dynamic update or IXFR are first saved to the  mas-
	      ter  files of the	updated	zones. If -p is	specified, named(8)`'s
	      process ID is returned.  This allows an external process to  de-
	      termine when ``named has completed stopping.

	      See also rndc halt.

       sync -clean [zone [class	[view]]]
	      This  command  syncs  changes  in	the journal file for a dynamic
	      zone to the master file. If the "-clean"	option	is  specified,
	      the  journal file	is also	removed. If no zone is specified, then
	      all zones	are synced.

       tcp-timeouts [initial idle keepalive advertised]
	      When called without arguments, this command displays the current
	      values	of    the    tcp-initial-timeout,    tcp-idle-timeout,
	      tcp-keepalive-timeout, and tcp-advertised-timeout	options.  When
	      called  with arguments, these values are updated.	This allows an
	      administrator  to	 make  rapid  adjustments  when	 under	a  de-
	      nial-of-service  (DoS) attack. See the descriptions of these op-
	      tions in the BIND	9 Administrator	Reference Manual  for  details
	      of their use.

       thaw [zone [class [view]]]
	      This  command  enables  updates  to a frozen dynamic zone. If no
	      zone is specified, then  all  frozen  zones  are	enabled.  This
	      causes  the  server to reload the	zone from disk,	and re-enables
	      dynamic updates after the	load has completed. After  a  zone  is
	      thawed,  dynamic	updates	are no longer refused. If the zone has
	      changed and the ixfr-from-differences  option  is	 in  use,  the
	      journal  file  is	updated	to reflect changes in the zone.	Other-
	      wise, if the zone	has changed, any existing journal file is  re-
	      moved.

	      See also rndc freeze.

       trace  This command increments the server's debugging level by one.

       trace level
	      This  command  sets  the server's	debugging level	to an explicit
	      value.

	      See also rndc notrace.

       tsig-delete keyname [view]
	      This command  deletes  a	given  TKEY-negotiated	key  from  the
	      server. This does	not apply to statically	configured TSIG	keys.

       tsig-list
	      This  command lists the names of all TSIG	keys currently config-
	      ured for use by named in each view. The list includes both stat-
	      ically configured	keys and dynamic TKEY-negotiated keys.

       validation (on |	off | status) [view ...]``
	      This  command enables, disables, or checks the current status of
	      DNSSEC validation. By default, validation	is enabled.

	      The cache	is flushed when	validation is  turned  on  or  off  to
	      avoid using data that might differ between states.

       zonestatus zone [class [view]]
	      This  command displays the current status	of the given zone, in-
	      cluding the master file name and any include files from which it
	      was loaded, when it was most recently loaded, the	current	serial
	      number, the number of nodes, whether the zone  supports  dynamic
	      updates,	whether	the zone is DNSSEC signed, whether it uses au-
	      tomatic DNSSEC key management or inline signing, and the	sched-
	      uled refresh or expiry times for the zone.

	      See also rndc showzone.

       rndc  commands  that specify zone names,	such as	reload,	retransfer, or
       zonestatus, can be ambiguous when applied to zones  of  type  redirect.
       Redirect	 zones	are always called ., and can be	confused with zones of
       type hint or with secondary copies of the root zone. To specify a redi-
       rect  zone, use the special zone	name -redirect,	without	a trailing pe-
       riod. (With a trailing period, this would specify a zone	called "-redi-
       rect".)

LIMITATIONS
       There  is  currently  no	 way to	provide	the shared secret for a	key_id
       without using the configuration file.

       Several error messages could be clearer.

SEE ALSO
       rndc.conf(5), rndc-confgen(8), named(8),	named.conf(5), ndc(8), BIND  9
       Administrator Reference Manual.

AUTHOR
       Internet	Systems	Consortium

COPYRIGHT
       2021, Internet Systems Consortium

9.16.21				  2021-09-07			       RNDC(8)

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

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

home | help