1unbound-anchor(8)               unbound 1.19.0               unbound-anchor(8)
2
3
4

NAME

6       unbound-anchor - Unbound anchor utility.
7

SYNOPSIS

9       unbound-anchor [opts]
10

DESCRIPTION

12       Unbound-anchor  performs  setup  or update of the root trust anchor for
13       DNSSEC validation.  The program  fetches  the  trust  anchor  with  the
14       method from RFC7958 when regular RFC5011 update fails to bring it up to
15       date.  It can be run (as root) from the commandline, or run as part  of
16       startup scripts.  Before you start the unbound(8) DNS server.
17
18       Suggested usage:
19
20            # in the init scripts.
21            # provide or update the root anchor (if necessary)
22            unbound-anchor -a "/var/lib/unbound/root.key"
23            # Please note usage of this root anchor is at your own risk
24            # and under the terms of our LICENSE (see source).
25            #
26            # start validating resolver
27            # the unbound.conf contains:
28            #   auto-trust-anchor-file: "/var/lib/unbound/root.key"
29            unbound -c unbound.conf
30
31       This  tool  provides  builtin  default contents for the root anchor and
32       root update certificate files.
33
34       It tests if the root anchor file works, and if not, and  an  update  is
35       possible, attempts to update the root anchor using the root update cer‐
36       tificate.  It performs a https fetch of root-anchors.xml and checks the
37       results  (RFC7958),  if  all checks are successful, it updates the root
38       anchor file.  Otherwise the root anchor file is unchanged.  It performs
39       RFC5011  tracking if the DNSSEC information available via the DNS makes
40       that possible.
41
42       It does not perform an update if the certificate  is  expired,  if  the
43       network is down or other errors occur.
44
45       The available options are:
46
47       -a file
48              The  root anchor key file, that is read in and written out.  De‐
49              fault is /var/lib/unbound/root.key.  If the file does not exist,
50              or is empty, a builtin root key is written to it.
51
52       -c file
53              The  root  update certificate file, that is read in.  Default is
54              /etc/unbound/icannbundle.pem.  If the file does not exist, or is
55              empty, a builtin certificate is used.
56
57       -l     List the builtin root key and builtin root update certificate on
58              stdout.
59
60       -u name
61              The server name, it connects to https://name.   Specify  without
62              https://  prefix.   The default is "data.iana.org".  It connects
63              to the port specified with -P.  You can pass an IPv4 address  or
64              IPv6 address (no brackets) if you want.
65
66       -S     Do not use SNI for the HTTPS connection.  Default is to use SNI.
67
68       -b address
69              The source address to bind to for domain resolution and contact‐
70              ing the server on https.  May be either an IPv4 address or  IPv6
71              address (no brackets).
72
73       -x path
74              The  pathname to the root-anchors.xml file on the server. (forms
75              URL with -u).  The default is /root-anchors/root-anchors.xml.
76
77       -s path
78              The pathname to the root-anchors.p7s file on the server.  (forms
79              URL  with  -u).   The default is /root-anchors/root-anchors.p7s.
80              This file has to be a PKCS7 signature over the xml  file,  using
81              the pem file (-c) as trust anchor.
82
83       -n name
84              The  emailAddress  for  the  Subject of the signer's certificate
85              from the p7s signature file.  Only signatures from this name are
86              allowed.   default  is dnssec@iana.org.  If you pass "" then the
87              emailAddress is not checked.
88
89       -4     Use IPv4 for domain resolution  and  contacting  the  server  on
90              https.  Default is to use IPv4 and IPv6 where appropriate.
91
92       -6     Use  IPv6  for  domain  resolution  and contacting the server on
93              https.  Default is to use IPv4 and IPv6 where appropriate.
94
95       -f resolv.conf
96              Use the given resolv.conf file.  Not enabled by default, but you
97              could try to pass /etc/resolv.conf on some systems.  It contains
98              the IP addresses of the recursive nameservers to use.   However,
99              since  this  tool could be used to bootstrap that very recursive
100              nameserver, it would not be useful (since that server is not  up
101              yet,  since  we  are bootstrapping it).  It could be useful in a
102              situation where you know an upstream cache is deployed (and run‐
103              ning) and in captive portal situations.
104
105       -r root.hints
106              Use  the  given root.hints file (same syntax as the BIND and Un‐
107              bound root hints file) to bootstrap domain resolution.   By  de‐
108              fault a list of builtin root hints is used.  Unbound-anchor goes
109              to the network itself for these roots, to resolve the server (-u
110              option)  and  to check the root DNSKEY records.  It does so, be‐
111              cause the tool when used for  bootstrapping  the  recursive  re‐
112              solver,  cannot use that recursive resolver itself because it is
113              bootstrapping that server.
114
115       -R     Allow fallback from -f resolv.conf file to direct  root  servers
116              query.   It  allows  you to prefer local resolvers, but fallback
117              automatically to direct root query if they do not respond or  do
118              not support DNSSEC.
119
120       -v     More verbose. Once prints informational messages, multiple times
121              may enable large debug amounts (such  as  full  certificates  or
122              byte-dumps  of  downloaded  files).  By default it prints almost
123              nothing.  It also prints nothing on errors by default;  in  that
124              case  the  original root anchor file is simply left undisturbed,
125              so that a recursive server can start right after it.
126
127       -C unbound.conf
128              Debug option to read  unbound.conf  into  the  resolver  process
129              used.
130
131       -P port
132              Set  the  port  number to use for the https connection.  The de‐
133              fault is 443.
134
135       -F     Debug option to force update of the root  anchor  through  down‐
136              loading  the xml file and verifying it with the certificate.  By
137              default it first tries to update by contacting  the  DNS,  which
138              uses  much  less bandwidth, is much faster (200 msec not 2 sec),
139              and is nicer to the deployed infrastructure.  With this  option,
140              it  still  attempts  to  do so (and may verbosely tell you), but
141              then ignores the result and goes on  to  use  the  xml  fallback
142              method.
143
144       -h     Show the version and commandline option help.
145

EXIT CODE

147       This  tool  exits with value 1 if the root anchor was updated using the
148       certificate or if the builtin root-anchor was used.  It exits with code
149       0  if  no update was necessary, if the update was possible with RFC5011
150       tracking, or if an error occurred.
151
152       You can check the exit value in this manner:
153            unbound-anchor -a "root.key" || logger "Please check root.key"
154       Or something more suitable for your operational environment.
155

TRUST

157       The root keys and update certificate included in this tool are provided
158       for  convenience  and  under  the terms of our license (see the LICENSE
159       file in the  source  distribution  or  https://github.com/NLnetLabs/un
160       bound/blob/master/LICENSE)  and  might be stale or not suitable to your
161       purpose.
162
163       By running "unbound-anchor -l" the  keys and certificate that are  con‐
164       figured in the code are printed for your convenience.
165
166       The  build-in  configuration can be overridden by providing a root-cert
167       file and a rootkey file.
168

FILES

170       /var/lib/unbound/root.key
171              The root anchor file, updated with 5011 tracking, and  read  and
172              written to.  The file is created if it does not exist.
173
174       /etc/unbound/icannbundle.pem
175              The  trusted  self-signed certificate that is used to verify the
176              downloaded DNSSEC root trust  anchor.   You  can  update  it  by
177              fetching  it  from  https://data.iana.org/root-anchors/icannbun
178              dle.pem (and validate it).  If the file does  not  exist  or  is
179              empty, a builtin version is used.
180
181       https://data.iana.org/root-anchors/root-anchors.xml
182              Source for the root key information.
183
184       https://data.iana.org/root-anchors/root-anchors.p7s
185              Signature on the root key information.
186

SEE ALSO

188       unbound.conf(5), unbound(8).
189
190
191
192NLnet Labs                       Nov  8, 2023                unbound-anchor(8)
Impressum