Section: unbound 1.4.20 (8)
Updated: Mar 21, 2013Index
unbound-anchor- Unbound anchor utility.
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 startupscripts. 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 rootupdate 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, ifall checks are successful, it updates the root anchor file. Otherwisethe root anchor file is unchanged. It performs RFC5011 tracking if theDNSSEC information available via the DNS makes that possible.It does not perform an update if the certificate is expired, if the networkis 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.
- 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 PKCS7signature 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 p7ssignature file. Only signatures from this name are allowed. default isdnssecAATTiana.org. If you pass "" then the emailAddress is not checked.
- Use IPv4 for domain resolution and contacting the server on https. Default isto use IPv4 and IPv6 where appropriate.
- Use IPv6 for domain resolution and contacting the server on https. Default isto use IPv4 and IPv6 where appropriate.
- -f resolv.conf
- Use the given resolv.conf file. Not enabled by default, but you could try topass /etc/resolv.conf on some systems. It contains the IP addresses of therecursive nameservers to use. However, since this tool could be used tobootstrap that very recursive nameserver, it would not be useful (sincethat server is not up yet, since we are bootstrapping it). It could beuseful in a situation where you know an upstream cache is deployed (andrunning) and in captive portal situations.
- -r root.hints
- Use the given root.hints file (same syntax as the BIND and Unbound root hintsfile) to bootstrap domain resolution. By default a list of builtin roothints 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 recursiveresolver, cannot use that recursive resolver itself because it is bootstrappingthat server.
- More verbose. Once prints informational messages, multiple times may enablelarge debug amounts (such as full certificates or byte-dumps of downloadedfiles). By default it prints almost nothing. It also prints nothing onerrors by default; in that case the original root anchor file is simplyleft 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.
- Debug option to force update of the root anchor through downloading the xmlfile and verifying it with the certificate. By default it first tries toupdate by contacting the DNS, which uses much less bandwidth, is muchfaster (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.
- Show the version and commandline option help.
This tool exits with value 1 if the root anchor was updated using thecertificate or if the builtin root-anchor was used. It exits with code0 if no update was necessary, if the update was possible with RFC5011tracking, 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 toolare provided for convenience and under the terms of ourlicense (see the LICENSE file in the source distribution orhttp://unbound.nlnetlabs.nl/svn/trunk/LICENSE)
and might be stale ornot suitable to your purpose.By running "unbound-anchor -l" the keys and certificate that areconfigured in the code are printed for your convenience.The build-in configuration can be overridden by providing a root-certfile 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 downloadedDNSSEC root trust anchor. You can update it by fetching it fromhttps://data.iana.org/root-anchors/icannbundle.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.
- EXIT CODE
- SEE ALSO
This document was created byman2html,using the manual pages.