UNBOUND-ANCHOR(8)

📦
version 1.26.2 · 17 versions
, in fedora 44

✨ UNBOUND-ANCHOR ✨ (section 8, bestie)

okay so this is unbound-anchor, it's the anchor utility that ships with Unbound 1.26.2, and it is literally the thing that sets up and keeps your DNSSEC root trust anchor fresh. let's get into it 💅

🌸 SYNOPSIS 🌸

unbound-anchor [opts]

that's it. that's the whole synopsis. she's simple like that 🎀

💖 DESCRIPTION 💖

unbound-anchor does the setup or the update of the root trust anchor for DNSSEC validation. when the regular RFC 5011 update is not bringing it up to date, the program goes and fetches the trust anchor using the method from RFC 7958. you can run it straight from the command line, or you can run it inside your startup scripts before you start the unbound(8) DNS server. either way works 🫶

okay important note bestie 📢 if you want to use RFC 5011 with Unbound (that's the auto-trust-anchor-file option) so that trust anchor info gets tracked automatically by Unbound while it's running, then the user Unbound runs under (by default 'unbound') has to have write permissions to the file and to the directory that file lives in (because it needs to create temporary files). and in that case, you'd probably want to run this program as that same designated Unbound user. no cap.

suggested usage, here it is verbatim:

# 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 comes with builtin default contents for the root anchor and the root update certificate files. built in. pre-loaded. iconic. 👑

here's the vibe of what it actually does: it tests whether the root anchor file works, and if it doesn't work, and an update is actually possible, it tries to update the root anchor using the root update certificate. it does an https fetch of root-anchors.xml and checks the results (RFC 7958), and if every single check passes it updates the root anchor file. if not? the root anchor file is left completely unchanged. it also performs RFC 5011 tracking if the DNSSEC information available over DNS makes that possible.

and listen — it will not do an update if the certificate is expired, if the network is down, or if other errors happen. it's not gonna just yolo it. 🙈

the available options are:

  • -a <file> — the root anchor key file, which gets read in and written out. default is /var/lib/unbound/root.key. if the file doesn't exist, or it's empty, a builtin root key gets written to it. ✨
  • -c <file> — the root update certificate file, which gets read in. default is /etc/unbound/icannbundle.pem. if the file doesn't exist, or it's empty, a builtin certificate is used instead.
  • -l — list the builtin root key and the builtin root update certificate on stdout. 👀
  • -u <name> — the server name, it connects to https://name. give it without the https:// prefix. the default is "data.iana.org". it connects to whatever port you set with -P. you can also pass an IPv4 address or an IPv6 address (no brackets) if that's your thing.
  • -S — do not use SNI for the HTTPS connection. default behaviour is to use SNI.
  • -b <address> — the source address to bind to, for domain resolution and for contacting the server over https. can be either an IPv4 address or an IPv6 address (no brackets, bestie, no brackets).
  • -x <path> — the pathname to the root-anchors.xml file on the server. (it forms the URL together with -u.) default is /root-anchors/root-anchors.xml.
  • -s <path> — the pathname to the root-anchors.p7s file on the server. (forms the URL with -u.) 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 for contacting the server over https. default is to use IPv4 and IPv6 where appropriate.
  • -6 — use IPv6 for domain resolution and for contacting the server over 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 passing /etc/resolv.conf on some systems. it contains the IP addresses of the recursive nameservers to use. however — and this is the funny part — since this tool could be used to bootstrap that very recursive nameserver, it wouldn't be useful, because that server isn't up yet, because we're bootstrapping it. it could be useful in a situation where you know an upstream cache is deployed (and running), and in captive portal situations. iykyk 🌐
  • -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 that because when the tool is being used for bootstrapping the recursive resolver, it can't use that recursive resolver itself — because it's bootstrapping that server. circular. obsessed with the logic tbh.
  • -R — allow fallback from the -f <resolv.conf> file to a direct root servers query. this lets you prefer local resolvers, but automatically fall back to a direct root query if they don't respond or don't support DNSSEC. 🔁
  • -v — more verbose. once gives you informational messages, and multiple times may enable large debug amounts (like 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 just left undisturbed, so that a recursive server can start right after it. quiet queen. 🤫
  • -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. default is 443.
  • -F — debug option to force update of the root anchor by downloading the xml file and verifying it with the certificate. by default it first tries to update by contacting the DNS, which uses way less bandwidth, is way faster (200 msec not 2 sec), and is nicer to the deployed infrastructure. with this option it still attempts to do that (and may verbosely tell you), but then ignores the result and goes on to use the xml fallback method anyway. 💀
  • -h — show the version and the 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 RFC 5011 tracking, or if an error occurred. (yes bestie, error still means 0, that's just how she is. 😭)

you can check the exit value like this:

unbound-anchor -a "root.key" || logger "Please check root.key"

or literally anything else that suits your operational environment. do you. 🫶

🔐 TRUST 🔐

the root keys and the 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 https://github.com/NLnetLabs/unbound/blob/master/LICENSE), and they might be stale or not suitable to your purpose. so like, be aware. 🙈

by running unbound-anchor -l the keys and certificate that are configured in the code get printed, for your convenience.

the built-in configuration can be overridden by providing a root-cert file and a rootkey file.

📁 FILES 📁

👀 SEE ALSO 👀

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

⭐ AUTHOR ⭐

the Unbound developers are mentioned in the CREDITS file in the distribution. stan them fr fr 💜

1999-2026, NLnet Labs

and that's the whole page bestie!! this was unbound-anchor, section 8, version 1.26.2, dated Oct 21, 2026. go forth and validate your DNSSEC root trust anchor responsibly, and remember — root keys are temporary, but the vibe is eternal. periodt 💅✨🦋

📦 where this page comes from