Provided by: unbound-anchor_1.6.7-1ubuntu2.6_amd64 bug

NAME

       unbound-anchor - Unbound anchor utility.

SYNOPSIS

       unbound-anchor [opts]

DESCRIPTION

       Unbound-anchor  performs  setup  or update of the root trust anchor for DNSSEC validation.
       The program fetches the trust anchor with the method from  RFC7958  when  regular  RFC5011
       update fails to bring it up to date.  It can be run (as root) from the commandline, or run
       as part of startup scripts.  Before you start the unbound(8) DNS server.

       Suggested usage:

            # in the init scripts.
            # provide or update the root anchor (if necessary)
            unbound-anchor -a "/var/lib/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/lib/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 certificate.  It performs a  https  fetch  of
       root-anchors.xml  and  checks  the  results  (RFC7958),  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 possible.

       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/lib/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
              /etc/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 stdout.

       -u name
              The server name, it connects to https://name.   Specify  without  https://  prefix.
              The  default  is  "data.iana.org".  It connects to the port specified with -P.  You
              can pass an IPv4 address 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 dnssec@iana.org.  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 running) 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  recursive  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 used.

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

       -h     Show the version and commandline option help.

EXIT CODE

       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.

TRUST

       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.nlnetlabs.nl/svn/trunk/LICENSE) and might be stale or not suitable to  your
       purpose.

       By  running  "unbound-anchor -l" the  keys and certificate that are configured 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.

FILES

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

       /etc/unbound/icannbundle.pem
              The trusted self-signed certificate that is used to verify  the  downloaded  DNSSEC
              root    trust    anchor.     You    can    update    it   by   fetching   it   from
              https://data.iana.org/root-anchors/icannbundle.pem (and validate it).  If the  file
              does not exist or is empty, a builtin version is used.

       https://data.iana.org/root-anchors/root-anchors.xml
              Source for the root key information.

       https://data.iana.org/root-anchors/root-anchors.p7s
              Signature on the root key information.

SEE ALSO

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