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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
unbound-anchor(8)               unbound 1.4.20               unbound-anchor(8)

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

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

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

NAME | SYNOPSIS | DESCRIPTION | EXIT CODE | TRUST | FILES | SEE ALSO

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

home | help