1unbound-anchor(8) unbound 1.4.13 unbound-anchor(8)
2
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. It can be run (as root) from the commandline, or
14 run as part of startup scripts. Before you start the unbound(8) DNS
15 server.
16 Suggested usage:
18 # in the init scripts.
20 # provide or update the root anchor (if necessary)
21 unbound-anchor -a "/etc/unbound/root.key"
22 # Please note usage of this root anchor is at your own risk
23 # and under the terms of our LICENSE (see source).
24 #
25 # start validating resolver
26 # the unbound.conf contains:
27 # auto-trust-anchor-file: "/etc/unbound/root.key"
28 unbound -c unbound.conf
29 This tool provides builtin default contents for the root anchor and
31 root update certificate files.
32 It tests if the root anchor file works, and if not, and an update is
34 possible, attempts to update the root anchor using the root update cer‐
35 tificate. It performs a https fetch of root-anchors.xml and checks the
36 results, if all checks are successful, it updates the root anchor file.
37 Otherwise the root anchor file is unchanged. It performs RFC5011
38 tracking if the DNSSEC information available via the DNS makes that
39 possible.
40 If does not perform an update if the certificate is expired, if the
42 network is down or other errors occur.
43 The available options are:
45 -a file
47 The root anchor key file, that is read in and written out.
48 Default is /etc/unbound/root.key. If the file does not exist,
49 or is empty, a builtin root key is written to it.
50 -c file
52 The root update certificate file, that is read in. Default is
53 /etc/unbound/icannbundle.pem. If the file does not exist, or is
54 empty, a builtin certificate is used.
55 -l List the builtin root key and builtin root update certificate on
57 stdout.
58 -u name
60 The server name, it connects to https://name. Specify without
61 https:// prefix. The default is "data.iana.org". It connects
62 to the port specified with -P. You can pass an IPv4 addres or
63 IPv6 address (no brackets) if you want.
64 -x path
66 The pathname to the root-anchors.xml file on the server. (forms
67 URL with -u). The default is /root-anchors/root-anchors.xml.
68 -s path
70 The pathname to the root-anchors.p7s file on the server. (forms
71 URL with -u). The default is /root-anchors/root-anchors.p7s.
72 This file has to be a PKCS7 signature over the xml file, using
73 the pem file (-c) as trust anchor.
74 -4 Use IPv4 for domain resolution and contacting the server on
76 https. Default is to use IPv4 and IPv6 where appropriate.
77 -6 Use IPv6 for domain resolution and contacting the server on
79 https. Default is to use IPv4 and IPv6 where appropriate.
80 -f resolv.conf
82 Use the given resolv.conf file. Not enabled by default, but you
83 could try to pass /etc/resolv.conf on some systems. It contains
84 the IP addresses of the recursive nameservers to use. However,
85 since this tool could be used to bootstrap that very recursive
86 nameserver, it would not be useful (since that server is not up
87 yet, since we are bootstrapping it). It could be useful in a
88 situation where you know an upstream cache is deployed (and run‐
89 ning) and in captive portal situations.
90 -r root.hints
92 Use the given root.hints file (same syntax as the BIND and
93 Unbound root hints file) to bootstrap domain resolution. By
94 default a list of builtin root hints is used. Unbound-anchor
95 goes to the network itself for these roots, to resolve the
96 server (-u option) and to check the root DNSKEY records. It
97 does so, because the tool when used for bootstrapping the recur‐
98 sive resolver, cannot use that recursive resolver itself because
99 it is bootstrapping that server.
100 -v More verbose. Once prints informational messages, multiple times
102 may enable large debug amounts (such as full certificates or
103 byte-dumps of downloaded files). By default it prints almost
104 nothing. It also prints nothing on errors by default; in that
105 case the original root anchor file is simply left undisturbed,
106 so that a recursive server can start right after it.
107 -C unbound.conf
109 Debug option to read unbound.conf into the resolver process
110 used.
111 -P port
113 Set the port number to use for the https connection. The
114 default is 443.
115 -F Debug option to force update of the root anchor through down‐
117 loading the xml file and verifying it with the certificate. By
118 default it first tries to update by contacting the DNS, which
119 uses much less bandwidth, is much faster (200 msec not 2 sec),
120 and is nicer to the deployed infrastructure. With this option,
121 it still attempts to do so (and may verbosely tell you), but
122 then ignores the result and goes on to use the xml fallback
123 method.
124 -h Show the version and commandline option help.
126 -v More verbose. Prints output detailing what happens.
128
130 This tool exits with value 1 if the root anchor was updated using the
131 certificate or if the builtin root-anchor was used. It exits with code
132 0 if no update was necessary, if the update was possible with RFC5011
133 tracking, or if an error occurred.
134 You can check the exit value in this manner:
136 unbound-anchor -a "root.key" || logger "Please check root.key"
137 Or something more suitable for your operational environment.
138
140 The root keys and update certificate included in this tool are provided
141 for convenience and under the terms of our license (see the LICENSE
142 file in the source distribution or http://unbound.nlnet‐
143 labs.nl/svn/trunk/LICENSE) and might be stale or not suitable to your
144 purpose.
145 By running "unbound-anchor -l" the keys and certificate that are con‐
147 figured in the code are printed for your convenience.
148 The build-in configuration can be overridden by providing a root-cert
150 file and a rootkey file.
151
153 /etc/unbound/root.key
154 The root anchor file, updated with 5011 tracking, and read and
155 written to. The file is created if it does not exist.
156 /etc/unbound/icannbundle.pem
158 The trusted self-signed certificate that is used to verify the
159 downloaded DNSSEC root trust anchor. You can update it by
160 fetching it from https://data.iana.org/root-anchors/icannbun‐
161 dle.pem (and validate it). If the file does not exist or is
162 empty, a builtin version is used.
163 https://data.iana.org/root-anchors/root-anchors.xml
165 Source for the root key information.
166 https://data.iana.org/root-anchors/root-anchors.p7s
168 Signature on the root key information.
169
171 unbound.conf(5), unbound(8).
172NLnet Labs Sep 15, 2011 unbound-anchor(8)