183 lines
7.2 KiB
Groff
183 lines
7.2 KiB
Groff
.TH "unbound-anchor" "8" "Jun 17, 2019" "NLnet Labs" "unbound 1.9.2"
|
|
.\"
|
|
.\" 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.
|
|
The program fetches the trust anchor with the method from RFC7958 when
|
|
regular RFC5011 update fails to bring it up to date.
|
|
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 "/var/unbound/root.key"
|
|
# 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: "/var/unbound/root.key"
|
|
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 (RFC7958),
|
|
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 /var/unbound/root.key.
|
|
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 /var/unbound/icannbundle.pem.
|
|
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 address 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 \-R
|
|
Allow fallback from \-f resolv.conf file to direct root servers query.
|
|
It allows you to prefer local resolvers, but fallback automatically
|
|
to direct root query if they do not respond or do not support DNSSEC.
|
|
.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 /var/unbound/root.key
|
|
The root anchor file, updated with 5011 tracking, and read and written to.
|
|
The file is created if it does not exist.
|
|
.TP
|
|
.I /var/unbound/icannbundle.pem
|
|
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).
|