aboutsummaryrefslogtreecommitdiff
path: root/external/unbound/doc/unbound-anchor.8.in
diff options
context:
space:
mode:
authorRiccardo Spagni <ric@spagni.net>2014-10-05 23:44:31 +0200
committerRiccardo Spagni <ric@spagni.net>2014-10-05 23:44:31 +0200
commit9ef094b356b4da7542c3cab898dac7e135b76903 (patch)
tree99b5876712b0b1551fc042fe75447b998e4b0fc1 /external/unbound/doc/unbound-anchor.8.in
parentsplit mnemonic printout over 3 lines (diff)
downloadmonero-9ef094b356b4da7542c3cab898dac7e135b76903.tar.xz
added unbound to external deps
Diffstat (limited to 'external/unbound/doc/unbound-anchor.8.in')
-rw-r--r--external/unbound/doc/unbound-anchor.8.in175
1 files changed, 175 insertions, 0 deletions
diff --git a/external/unbound/doc/unbound-anchor.8.in b/external/unbound/doc/unbound-anchor.8.in
new file mode 100644
index 000000000..0c0e9e142
--- /dev/null
+++ b/external/unbound/doc/unbound-anchor.8.in
@@ -0,0 +1,175 @@
+.TH "unbound-anchor" "8" "@date@" "NLnet Labs" "unbound @version@"
+.\"
+.\" unbound-anchor.8 -- unbound anchor maintenance utility manual
+.\"
+.\" Copyright (c) 2008, NLnet Labs. All rights reserved.
+.\"
+.\" See LICENSE for the license.
+.\"
+.\"
+.SH "NAME"
+.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).