diff options
Diffstat (limited to 'contrib/unbound/doc/unbound-anchor.8.in')
| -rw-r--r-- | contrib/unbound/doc/unbound-anchor.8.in | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/contrib/unbound/doc/unbound-anchor.8.in b/contrib/unbound/doc/unbound-anchor.8.in new file mode 100644 index 0000000..41b18ed --- /dev/null +++ b/contrib/unbound/doc/unbound-anchor.8.in @@ -0,0 +1,176 @@ +.TH "unbound-anchor" "8" "Mar 12, 2014" "NLnet Labs" "unbound 1.4.22" +.\" +.\" unbound-anchor.8 -- unbound anchor maintenance utility manual +.\" +.\" Copyright (c) 2008, NLnet Labs. All rights reserved. +.\" +.\" See LICENSE for the license. +.\" +.\" +.SH "NAME" +.LP +.B unbound\-anchor +\- Unbound anchor utility. +.SH "SYNOPSIS" +.B unbound\-anchor +.RB [ opts ] +.SH "DESCRIPTION" +.B Unbound\-anchor +performs setup or update of the root trust anchor for DNSSEC validation. +It can be run (as root) from the commandline, or run as part of startup +scripts. Before you start the \fIunbound\fR(8) DNS server. +.P +Suggested usage: +.P +.nf + # in the init scripts. + # provide or update the root anchor (if necessary) + unbound-anchor -a "@UNBOUND_ROOTKEY_FILE@" + # Please note usage of this root anchor is at your own risk + # and under the terms of our LICENSE (see source). + # + # start validating resolver + # the unbound.conf contains: + # auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@" + unbound -c unbound.conf +.fi +.P +This tool provides builtin default contents for the root anchor and root +update certificate files. +.P +It tests if the root anchor file works, and if not, and an update is possible, +attempts to update the root anchor using the root update certificate. +It performs a https fetch of root-anchors.xml and checks the results, if +all checks are successful, it updates the root anchor file. Otherwise +the root anchor file is unchanged. It performs RFC5011 tracking if the +DNSSEC information available via the DNS makes that possible. +.P +It does not perform an update if the certificate is expired, if the network +is down or other errors occur. +.P +The available options are: +.TP +.B \-a \fIfile +The root anchor key file, that is read in and written out. +Default is @UNBOUND_ROOTKEY_FILE@. +If the file does not exist, or is empty, a builtin root key is written to it. +.TP +.B \-c \fIfile +The root update certificate file, that is read in. +Default is @UNBOUND_ROOTCERT_FILE@. +If the file does not exist, or is empty, a builtin certificate is used. +.TP +.B \-l +List the builtin root key and builtin root update certificate on stdout. +.TP +.B \-u \fIname +The server name, it connects to https://name. Specify without https:// prefix. +The default is "data.iana.org". It connects to the port specified with \-P. +You can pass an IPv4 addres or IPv6 address (no brackets) if you want. +.TP +.B \-x \fIpath +The pathname to the root\-anchors.xml file on the server. (forms URL with \-u). +The default is /root\-anchors/root\-anchors.xml. +.TP +.B \-s \fIpath +The pathname to the root\-anchors.p7s file on the server. (forms URL with \-u). +The default is /root\-anchors/root\-anchors.p7s. This file has to be a PKCS7 +signature over the xml file, using the pem file (\-c) as trust anchor. +.TP +.B \-n \fIname +The emailAddress for the Subject of the signer's certificate from the p7s +signature file. Only signatures from this name are allowed. default is +dnssec@iana.org. If you pass "" then the emailAddress is not checked. +.TP +.B \-4 +Use IPv4 for domain resolution and contacting the server on https. Default is +to use IPv4 and IPv6 where appropriate. +.TP +.B \-6 +Use IPv6 for domain resolution and contacting the server on https. Default is +to use IPv4 and IPv6 where appropriate. +.TP +.B \-f \fIresolv.conf +Use the given resolv.conf file. Not enabled by default, but you could try to +pass /etc/resolv.conf on some systems. It contains the IP addresses of the +recursive nameservers to use. However, since this tool could be used to +bootstrap that very recursive nameserver, it would not be useful (since +that server is not up yet, since we are bootstrapping it). It could be +useful in a situation where you know an upstream cache is deployed (and +running) and in captive portal situations. +.TP +.B \-r \fIroot.hints +Use the given root.hints file (same syntax as the BIND and Unbound root hints +file) to bootstrap domain resolution. By default a list of builtin root +hints is used. Unbound\-anchor goes to the network itself for these roots, +to resolve the server (\-u option) and to check the root DNSKEY records. +It does so, because the tool when used for bootstrapping the recursive +resolver, cannot use that recursive resolver itself because it is bootstrapping +that server. +.TP +.B \-v +More verbose. Once prints informational messages, multiple times may enable +large debug amounts (such as full certificates or byte\-dumps of downloaded +files). By default it prints almost nothing. It also prints nothing on +errors by default; in that case the original root anchor file is simply +left undisturbed, so that a recursive server can start right after it. +.TP +.B \-C \fIunbound.conf +Debug option to read unbound.conf into the resolver process used. +.TP +.B \-P \fIport +Set the port number to use for the https connection. The default is 443. +.TP +.B \-F +Debug option to force update of the root anchor through downloading the xml +file and verifying it with the certificate. By default it first tries to +update by contacting the DNS, which uses much less bandwidth, is much +faster (200 msec not 2 sec), and is nicer to the deployed infrastructure. +With this option, it still attempts to do so (and may verbosely tell you), +but then ignores the result and goes on to use the xml fallback method. +.TP +.B \-h +Show the version and commandline option help. +.SH "EXIT CODE" +This tool exits with value 1 if the root anchor was updated using the +certificate or if the builtin root-anchor was used. It exits with code +0 if no update was necessary, if the update was possible with RFC5011 +tracking, or if an error occurred. +.P +You can check the exit value in this manner: +.nf + unbound-anchor -a "root.key" || logger "Please check root.key" +.fi +Or something more suitable for your operational environment. +.SH "TRUST" +The root keys and update certificate included in this tool +are provided for convenience and under the terms of our +license (see the LICENSE file in the source distribution or +http://unbound.nlnetlabs.nl/svn/trunk/LICENSE) and might be stale or +not suitable to your purpose. +.P +By running "unbound\-anchor \-l" the keys and certificate that are +configured in the code are printed for your convenience. +.P +The build\-in configuration can be overridden by providing a root\-cert +file and a rootkey file. +.SH "FILES" +.TP +.I @UNBOUND_ROOTKEY_FILE@ +The root anchor file, updated with 5011 tracking, and read and written to. +The file is created if it does not exist. +.TP +.I @UNBOUND_ROOTCERT_FILE@ +The trusted self\-signed certificate that is used to verify the downloaded +DNSSEC root trust anchor. You can update it by fetching it from +https://data.iana.org/root\-anchors/icannbundle.pem (and validate it). +If the file does not exist or is empty, a builtin version is used. +.TP +.I https://data.iana.org/root\-anchors/root\-anchors.xml +Source for the root key information. +.TP +.I https://data.iana.org/root\-anchors/root\-anchors.p7s +Signature on the root key information. +.SH "SEE ALSO" +\fIunbound.conf\fR(5), +\fIunbound\fR(8). |
