1.. 2 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 3 4.. 5 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 6 7.. 8 IT HELPS PEOPLE DIFFING THE CHANGES 9 10.. 11 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 12 13.. 14 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 15 16.. 17 IT HELPS PEOPLE DIFFING THE CHANGES 18 19.. 20 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 21 22.. 23 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 24 25.. 26 IT HELPS PEOPLE DIFFING THE CHANGES 27 28.. 29 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 30 31.. 32 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 33 34.. 35 IT HELPS PEOPLE DIFFING THE CHANGES 36 37.. program:: unbound-anchor 38 39unbound-anchor(8) 40================= 41 42Synopsis 43-------- 44 45**unbound-anchor** [``opts``] 46 47Description 48----------- 49 50``unbound-anchor`` performs setup or update of the root trust anchor for DNSSEC 51validation. 52The program fetches the trust anchor with the method from :rfc:`7958` when 53regular :rfc:`5011` update fails to bring it up to date. 54It can be run (as root) from the commandline, or run as part of startup 55scripts. 56Before you start the :doc:`unbound(8)</manpages/unbound>` DNS server. 57 58Suggested usage: 59 60.. code-block:: text 61 62 # in the init scripts. 63 # provide or update the root anchor (if necessary) 64 unbound-anchor -a "@UNBOUND_ROOTKEY_FILE@" 65 # Please note usage of this root anchor is at your own risk 66 # and under the terms of our LICENSE (see source). 67 # 68 # start validating resolver 69 # the unbound.conf contains: 70 # auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@" 71 unbound -c unbound.conf 72 73This tool provides builtin default contents for the root anchor and root update 74certificate files. 75 76It tests if the root anchor file works, and if not, and an update is possible, 77attempts to update the root anchor using the root update certificate. 78It performs a https fetch of 79`root-anchors.xml <http://data.iana.org/root-anchors/root-anchors.xml>`__ 80and checks the results (:rfc:`7958`); if all checks are successful, it updates 81the root anchor file. 82Otherwise the root anchor file is unchanged. 83It performs :rfc:`5011` tracking if the DNSSEC information available via the 84DNS makes that possible. 85 86It does not perform an update if the certificate is expired, if the network is 87down or other errors occur. 88 89The available options are: 90 91.. option:: -a <file> 92 93 The root anchor key file, that is read in and written out. 94 Default is :file:`@UNBOUND_ROOTKEY_FILE@`. 95 If the file does not exist, or is empty, a builtin root key is written 96 to it. 97 98.. option:: -c <file> 99 100 The root update certificate file, that is read in. 101 Default is :file:`@UNBOUND_ROOTCERT_FILE@`. 102 If the file does not exist, or is empty, a builtin certificate is used. 103 104.. option:: -l 105 106 List the builtin root key and builtin root update certificate on stdout. 107 108.. option:: -u <name> 109 110 The server name, it connects to ``https://name``. 111 Specify without ``https://`` prefix. 112 The default is ``"data.iana.org"``. 113 It connects to the port specified with :option:`-P`. 114 You can pass an IPv4 address or IPv6 address (no brackets) if you want. 115 116.. option:: -S 117 118 Do not use SNI for the HTTPS connection. 119 Default is to use SNI. 120 121.. option:: -b <address> 122 123 The source address to bind to for domain resolution and contacting the 124 server on https. 125 May be either an IPv4 address or IPv6 address (no brackets). 126 127.. option:: -x <path> 128 129 The pathname to the root-anchors.xml file on the server. 130 (forms URL with :option:`-u`). 131 The default is :file:`/root-anchors/root-anchors.xml`. 132 133.. option:: -s <path> 134 135 The pathname to the root-anchors.p7s file on the server. 136 (forms URL with :option:`-u`). 137 The default is :file:`/root-anchors/root-anchors.p7s`. 138 This file has to be a PKCS7 signature over the xml file, using the pem 139 file (:option:`-c`) as trust anchor. 140 141.. option:: -n <name> 142 143 The emailAddress for the Subject of the signer's certificate from the 144 p7s signature file. 145 Only signatures from this name are allowed. 146 The default is ``dnssec@iana.org``. 147 If you pass ``""`` then the emailAddress is not checked. 148 149.. option:: -4 150 151 Use IPv4 for domain resolution and contacting the server on 152 https. 153 Default is to use IPv4 and IPv6 where appropriate. 154 155.. option:: -6 156 157 Use IPv6 for domain resolution and contacting the server on https. 158 Default is to use IPv4 and IPv6 where appropriate. 159 160.. option:: -f <resolv.conf> 161 162 Use the given resolv.conf file. 163 Not enabled by default, but you could try to pass 164 :file:`/etc/resolv.conf` on some systems. 165 It contains the IP addresses of the recursive nameservers to use. 166 However, since this tool could be used to bootstrap that very recursive 167 nameserver, it would not be useful (since that server is not up yet, 168 since we are bootstrapping it). 169 It could be useful in a situation where you know an upstream cache is 170 deployed (and running) and in captive portal situations. 171 172.. option:: -r <root.hints> 173 174 Use the given root.hints file (same syntax as the BIND and Unbound root 175 hints file) to bootstrap domain resolution. 176 By default a list of builtin root hints is used. 177 unbound-anchor goes to the network itself for these roots, to resolve 178 the server (:option:`-u` option) and to check the root DNSKEY records. 179 It does so, because the tool when used for bootstrapping the recursive 180 resolver, cannot use that recursive resolver itself because it is 181 bootstrapping that server. 182 183.. option:: -R 184 185 Allow fallback from :option:`-f` ``<resolv.conf>`` file to direct root 186 servers query. 187 It allows you to prefer local resolvers, but fallback automatically to 188 direct root query if they do not respond or do not support DNSSEC. 189 190.. option:: -v 191 192 More verbose. 193 Once prints informational messages, multiple times may enable large 194 debug amounts (such as full certificates or byte-dumps of downloaded 195 files). 196 By default it prints almost nothing. 197 It also prints nothing on errors by default; in that case the original 198 root anchor file is simply left undisturbed, so that a recursive server 199 can start right after it. 200 201.. option:: -C <unbound.conf> 202 203 Debug option to read :file:`<unbound.conf>` into the resolver process 204 used. 205 206.. option:: -P <port> 207 208 Set the port number to use for the https connection. 209 The default is 443. 210 211.. option:: -F 212 213 Debug option to force update of the root anchor through downloading the 214 xml file and verifying it with the certificate. 215 By default it first tries to update by contacting the DNS, which uses 216 much less bandwidth, is much faster (200 msec not 2 sec), and is nicer 217 to the deployed infrastructure. 218 With this option, it still attempts to do so (and may verbosely tell 219 you), but then ignores the result and goes on to use the xml fallback 220 method. 221 222.. option:: -h 223 224 Show the version and commandline option help. 225 226Exit Code 227--------- 228 229This tool exits with value 1 if the root anchor was updated using the 230certificate or if the builtin root-anchor was used. 231It exits with code 0 if no update was necessary, if the update was possible 232with :rfc:`5011` tracking, or if an error occurred. 233 234You can check the exit value in this manner: 235 236.. code-block:: text 237 238 unbound-anchor -a "root.key" || logger "Please check root.key" 239 240Or something more suitable for your operational environment. 241 242Trust 243----- 244 245The root keys and update certificate included in this tool are provided for 246convenience and under the terms of our license (see the LICENSE file in the 247source distribution or https://github.com/NLnetLabs/unbound/blob/master/LICENSE 248and might be stale or not suitable to your purpose. 249 250By running :option:`unbound-anchor -l` the keys and certificate that are 251configured in the code are printed for your convenience. 252 253The built-in configuration can be overridden by providing a root-cert file and 254a rootkey file. 255 256Files 257----- 258 259@UNBOUND_ROOTKEY_FILE@ 260 The root anchor file, updated with 5011 tracking, and read and written 261 to. 262 The file is created if it does not exist. 263 264@UNBOUND_ROOTCERT_FILE@ 265 The trusted self-signed certificate that is used to verify the 266 downloaded DNSSEC root trust anchor. 267 You can update it by fetching it from 268 https://data.iana.org/root-anchors/icannbundle.pem (and validate it). 269 If the file does not exist or is empty, a builtin version is used. 270 271https://data.iana.org/root-anchors/root-anchors.xml 272 Source for the root key information. 273 274https://data.iana.org/root-anchors/root-anchors.p7s 275 Signature on the root key information. 276 277See Also 278-------- 279 280:doc:`unbound.conf(5)</manpages/unbound.conf>`, 281:doc:`unbound(8)</manpages/unbound>`. 282