unbound-anchor(8) unbound 1.18.0 unbound-anchor(8) #
unbound-anchor(8) unbound 1.18.0 unbound-anchor(8)
NNAAMMEE #
uunnbboouunndd--aanncchhoorr - Unbound anchor utility.
SSYYNNOOPPSSIISS #
uunnbboouunndd--aanncchhoorr [ooppttss]
DDEESSCCRRIIPPTTIIOONN #
UUnnbboouunndd--aanncchhoorr 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 _u_n_b_o_u_n_d(8) DNS server.
Suggested usage:
# in the init scripts.
# provide or update the root anchor (if necessary)
unbound-anchor -a "/var/unbound/db/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/db/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:
--aa _f_i_l_e
The root anchor key file, that is read in and written out.
Default is /var/unbound/db/root.key. If the file does not exist,
or is empty, a builtin root key is written to it.
--cc _f_i_l_e
The root update certificate file, that is read in. Default is
/var/unbound/etc/icannbundle.pem. If the file does not exist, or
is empty, a builtin certificate is used.
--ll List the builtin root key and builtin root update certificate on
stdout.
--uu _n_a_m_e
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.
--SS Do not use SNI for the HTTPS connection. Default is to use SNI.
--bb _a_d_d_r_e_s_s
The source address to bind to for domain resolution and contacting
the server on https. May be either an IPv4 address or IPv6
address (no brackets).
--xx _p_a_t_h
The pathname to the root-anchors.xml file on the server. (forms
URL with -u). The default is /root-anchors/root-anchors.xml.
--ss _p_a_t_h
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.
--nn _n_a_m_e
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.
--44 Use IPv4 for domain resolution and contacting the server on https.
Default is to use IPv4 and IPv6 where appropriate.
--66 Use IPv6 for domain resolution and contacting the server on https.
Default is to use IPv4 and IPv6 where appropriate.
--ff _r_e_s_o_l_v_._c_o_n_f
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.
--rr _r_o_o_t_._h_i_n_t_s
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.
--RR Allow fallback from -f resolv.conf file to direct root servers
query. It allows you to prefer local resolvers, but fallback
automatically to direct root query if they do not respond or do
not support DNSSEC.
--vv 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.
--CC _u_n_b_o_u_n_d_._c_o_n_f
Debug option to read unbound.conf into the resolver process used.
--PP _p_o_r_t
Set the port number to use for the https connection. The default
is 443.
--FF 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.
--hh Show the version and commandline option help.
EEXXIITT CCOODDEE #
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.
TTRRUUSSTT #
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
https://github.com/NLnetLabs/unbound/blob/master/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.
FFIILLEESS #
_/_v_a_r_/_u_n_b_o_u_n_d_/_d_b_/_r_o_o_t_._k_e_y
The root anchor file, updated with 5011 tracking, and read and
written to. The file is created if it does not exist.
_/_v_a_r_/_u_n_b_o_u_n_d_/_e_t_c_/_i_c_a_n_n_b_u_n_d_l_e_._p_e_m
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.
_h_t_t_p_s_:_/_/_d_a_t_a_._i_a_n_a_._o_r_g_/_r_o_o_t_-_a_n_c_h_o_r_s_/_r_o_o_t_-_a_n_c_h_o_r_s_._x_m_l
Source for the root key information.
_h_t_t_p_s_:_/_/_d_a_t_a_._i_a_n_a_._o_r_g_/_r_o_o_t_-_a_n_c_h_o_r_s_/_r_o_o_t_-_a_n_c_h_o_r_s_._p_7_s
Signature on the root key information.
SSEEEE AALLSSOO #
_u_n_b_o_u_n_d_._c_o_n_f(5), _u_n_b_o_u_n_d(8).
NLnet Labs August 30, 2023 unbound-anchor(8)