doc/unbound-anchor.8.in

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