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

FreeBSD Manual Pages


home | help
unbound-anchor(8)		unbound	1.4.20		     unbound-anchor(8)

       unbound-anchor -	Unbound	anchor utility.

       unbound-anchor [opts]

       Unbound-anchor  performs	 setup	or update of the root trust anchor for
       DNSSEC validation.  It can be run (as root) from	 the  commandline,  or
       run  as	part  of startup scripts.  Before you start the	unbound(8) DNS

       Suggested usage:

	    # in the init scripts.
	    # provide or update	the root anchor	(if necessary)
	    unbound-anchor -a "/var/unbound/root.key"
	    # Please note usage	of this	root anchor is at your own risk
	    # and under	the terms of our LICENSE (see source).
	    # start validating resolver
	    # the unbound.conf contains:
	    #	auto-trust-anchor-file:	"/var/unbound/root.key"
	    unbound -c unbound.conf

       This tool provides builtin default contents for	the  root  anchor  and
       root update certificate files.

       It  tests  if  the root anchor file works, and if not, and an update is
       possible, attempts to update the	root anchor using the root update cer-
       tificate.  It performs a	https fetch of root-anchors.xml	and checks the
       results,	if all checks are successful, it updates the root anchor file.
       Otherwise  the  root  anchor  file  is  unchanged.  It performs RFC5011
       tracking	if the DNSSEC information available via	 the  DNS  makes  that

       It  does	 not  perform  an update if the	certificate is expired,	if the
       network is down or other	errors occur.

       The available options are:

       -a file
	      The root anchor key file,	that  is  read	in  and	 written  out.
	      Default  is  /var/unbound/root.key.  If the file does not	exist,
	      or is empty, a builtin root key is written to it.

       -c file
	      The root update certificate file,	that is	read in.   Default  is
	      /var/unbound/icannbundle.pem.  If	the file does not exist, or is
	      empty, a builtin certificate is used.

       -l     List the builtin root key	and builtin root update	certificate on

       -u name
	      The  server  name, it connects to	https://name.  Specify without
	      https:// prefix.	The default is "".	  It  connects
	      to  the  port specified with -P.	You can	pass an	IPv4 addres or
	      IPv6 address (no brackets) if you	want.

       -x path
	      The pathname to the root-anchors.xml file	on the server.	(forms
	      URL with -u).  The default is /root-anchors/root-anchors.xml.

       -s path
	      The  pathname to the root-anchors.p7s file on the	server.	(forms
	      URL with -u).  The  default  is  /root-anchors/root-anchors.p7s.
	      This  file  has to be a PKCS7 signature over the xml file, using
	      the pem file (-c)	as trust anchor.

       -n name
	      The emailAddress for the Subject	of  the	 signer's  certificate
	      from the p7s signature file.  Only signatures from this name are
	      allowed.	default	is  If	you pass ""  then  the
	      emailAddress is not checked.

       -4     Use  IPv4	 for  domain  resolution  and contacting the server on
	      https.  Default is to use	IPv4 and IPv6 where appropriate.

       -6     Use IPv6 for domain resolution  and  contacting  the  server  on
	      https.  Default is to use	IPv4 and IPv6 where appropriate.

       -f resolv.conf
	      Use the given resolv.conf	file.  Not enabled by default, but you
	      could try	to pass	/etc/resolv.conf on some systems.  It contains
	      the  IP addresses	of the recursive nameservers to	use.  However,
	      since this tool could be used to bootstrap that  very  recursive
	      nameserver,  it would not	be useful (since that server is	not up
	      yet, since we are	bootstrapping it).  It could be	 useful	 in  a
	      situation	where you know an upstream cache is deployed (and run-
	      ning) and	in captive portal situations.

       -r root.hints
	      Use the given root.hints file  (same  syntax  as	the  BIND  and
	      Unbound  root  hints  file)  to bootstrap	domain resolution.  By
	      default a	list of	builtin	root hints  is	used.	Unbound-anchor
	      goes  to	the  network  itself  for  these roots,	to resolve the
	      server (-u option) and to	check the  root	 DNSKEY	 records.   It
	      does so, because the tool	when used for bootstrapping the	recur-
	      sive resolver, cannot use	that recursive resolver	itself because
	      it is bootstrapping that server.

       -v     More verbose. Once prints	informational messages,	multiple times
	      may enable large debug amounts (such  as	full  certificates  or
	      byte-dumps  of  downloaded  files).  By default it prints	almost
	      nothing.	It also	prints nothing on errors by default;  in  that
	      case  the	 original root anchor file is simply left undisturbed,
	      so that a	recursive server can start right after it.

       -C unbound.conf
	      Debug option to read  unbound.conf  into	the  resolver  process

       -P port
	      Set  the	port  number  to  use  for  the	https connection.  The
	      default is 443.

       -F     Debug option to force update of the root	anchor	through	 down-
	      loading  the xml file and	verifying it with the certificate.  By
	      default it first tries to	update by contacting  the  DNS,	 which
	      uses  much  less bandwidth, is much faster (200 msec not 2 sec),
	      and is nicer to the deployed infrastructure.  With this  option,
	      it  still	 attempts  to  do so (and may verbosely	tell you), but
	      then ignores the result and goes on  to  use  the	 xml  fallback

       -h     Show the version and commandline option help.

       This  tool  exits with value 1 if the root anchor was updated using the
       certificate or if the builtin root-anchor was used.  It exits with code
       0  if  no update	was necessary, if the update was possible with RFC5011
       tracking, or if an error	occurred.

       You can check the exit value in this manner:
	    unbound-anchor -a "root.key" || logger "Please check root.key"
       Or something more suitable for your operational environment.

       The root	keys and update	certificate included in	this tool are provided
       for  convenience	 and  under  the terms of our license (see the LICENSE
       file   in   the	 source	   distribution	   or	 http://unbound.nlnet-  and	might be stale or not suitable to your

       By running "unbound-anchor -l" the  keys	and certificate	that are  con-
       figured in the code are printed for your	convenience.

       The  build-in  configuration can	be overridden by providing a root-cert
       file and	a rootkey file.

	      The root anchor file, updated with 5011 tracking,	and  read  and
	      written to.  The file is created if it does not exist.

	      The  trusted  self-signed	certificate that is used to verify the
	      downloaded DNSSEC	root trust  anchor.   You  can	update	it  by
	      fetching	it  from
	      dle.pem (and validate it).  If the file does  not	 exist	or  is
	      empty, a builtin version is used.
	      Source for the root key information.
	      Signature	on the root key	information.

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

NLnet Labs			 Mar 21, 2013		     unbound-anchor(8)


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

home | help