1unbound-anchor(8) unbound 1.10.0 unbound-anchor(8)
2
3
4
6 unbound-anchor - Unbound anchor utility.
7
9 unbound-anchor [opts]
10
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.
49 Default is /var/lib/unbound/root.key. If the file does not
50 exist, 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 -b address
67 The source address to bind to for domain resolution and contact‐
68 ing the server on https. May be either an IPv4 address or IPv6
69 address (no brackets).
70
71 -x path
72 The pathname to the root-anchors.xml file on the server. (forms
73 URL with -u). The default is /root-anchors/root-anchors.xml.
74
75 -s path
76 The pathname to the root-anchors.p7s file on the server. (forms
77 URL with -u). The default is /root-anchors/root-anchors.p7s.
78 This file has to be a PKCS7 signature over the xml file, using
79 the pem file (-c) as trust anchor.
80
81 -n name
82 The emailAddress for the Subject of the signer's certificate
83 from the p7s signature file. Only signatures from this name are
84 allowed. default is dnssec@iana.org. If you pass "" then the
85 emailAddress is not checked.
86
87 -4 Use IPv4 for domain resolution and contacting the server on
88 https. Default is to use IPv4 and IPv6 where appropriate.
89
90 -6 Use IPv6 for domain resolution and contacting the server on
91 https. Default is to use IPv4 and IPv6 where appropriate.
92
93 -f resolv.conf
94 Use the given resolv.conf file. Not enabled by default, but you
95 could try to pass /etc/resolv.conf on some systems. It contains
96 the IP addresses of the recursive nameservers to use. However,
97 since this tool could be used to bootstrap that very recursive
98 nameserver, it would not be useful (since that server is not up
99 yet, since we are bootstrapping it). It could be useful in a
100 situation where you know an upstream cache is deployed (and run‐
101 ning) and in captive portal situations.
102
103 -r root.hints
104 Use the given root.hints file (same syntax as the BIND and
105 Unbound root hints file) to bootstrap domain resolution. By
106 default a list of builtin root hints is used. Unbound-anchor
107 goes to the network itself for these roots, to resolve the
108 server (-u option) and to check the root DNSKEY records. It
109 does so, because the tool when used for bootstrapping the recur‐
110 sive resolver, cannot use that recursive resolver itself because
111 it is bootstrapping that server.
112
113 -R Allow fallback from -f resolv.conf file to direct root servers
114 query. It allows you to prefer local resolvers, but fallback
115 automatically to direct root query if they do not respond or do
116 not support DNSSEC.
117
118 -v More verbose. Once prints informational messages, multiple times
119 may enable large debug amounts (such as full certificates or
120 byte-dumps of downloaded files). By default it prints almost
121 nothing. It also prints nothing on errors by default; in that
122 case the original root anchor file is simply left undisturbed,
123 so that a recursive server can start right after it.
124
125 -C unbound.conf
126 Debug option to read unbound.conf into the resolver process
127 used.
128
129 -P port
130 Set the port number to use for the https connection. The
131 default is 443.
132
133 -F Debug option to force update of the root anchor through down‐
134 loading the xml file and verifying it with the certificate. By
135 default it first tries to update by contacting the DNS, which
136 uses much less bandwidth, is much faster (200 msec not 2 sec),
137 and is nicer to the deployed infrastructure. With this option,
138 it still attempts to do so (and may verbosely tell you), but
139 then ignores the result and goes on to use the xml fallback
140 method.
141
142 -h Show the version and commandline option help.
143
145 This tool exits with value 1 if the root anchor was updated using the
146 certificate or if the builtin root-anchor was used. It exits with code
147 0 if no update was necessary, if the update was possible with RFC5011
148 tracking, or if an error occurred.
149
150 You can check the exit value in this manner:
151 unbound-anchor -a "root.key" || logger "Please check root.key"
152 Or something more suitable for your operational environment.
153
155 The root keys and update certificate included in this tool are provided
156 for convenience and under the terms of our license (see the LICENSE
157 file in the source distribution or http://unbound.nlnet‐
158 labs.nl/svn/trunk/LICENSE) and might be stale or not suitable to your
159 purpose.
160
161 By running "unbound-anchor -l" the keys and certificate that are con‐
162 figured in the code are printed for your convenience.
163
164 The build-in configuration can be overridden by providing a root-cert
165 file and a rootkey file.
166
168 /var/lib/unbound/root.key
169 The root anchor file, updated with 5011 tracking, and read and
170 written to. The file is created if it does not exist.
171
172 /etc/unbound/icannbundle.pem
173 The trusted self-signed certificate that is used to verify the
174 downloaded DNSSEC root trust anchor. You can update it by
175 fetching it from https://data.iana.org/root-anchors/icannbun‐
176 dle.pem (and validate it). If the file does not exist or is
177 empty, a builtin version is used.
178
179 https://data.iana.org/root-anchors/root-anchors.xml
180 Source for the root key information.
181
182 https://data.iana.org/root-anchors/root-anchors.p7s
183 Signature on the root key information.
184
186 unbound.conf(5), unbound(8).
187
188
189
190NLnet Labs Feb 20, 2020 unbound-anchor(8)