diff options
Diffstat (limited to 'contrib/unbound/doc/unbound-anchor.8.in')
| -rw-r--r-- | contrib/unbound/doc/unbound-anchor.8.in | 383 |
1 files changed, 247 insertions, 136 deletions
diff --git a/contrib/unbound/doc/unbound-anchor.8.in b/contrib/unbound/doc/unbound-anchor.8.in index f93c5d0cd045..6b75e3c3874f 100644 --- a/contrib/unbound/doc/unbound-anchor.8.in +++ b/contrib/unbound/doc/unbound-anchor.8.in @@ -1,189 +1,300 @@ -.TH "unbound-anchor" "8" "Jul 16, 2025" "NLnet Labs" "unbound 1.23.1" -.\" -.\" 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. +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "UNBOUND-ANCHOR" "8" "Sep 18, 2025" "1.24.0" "Unbound" +.SH NAME +unbound-anchor \- Unbound 1.24.0 anchor utility. +.SH SYNOPSIS +.sp +\fBunbound\-anchor\fP [\fBopts\fP] +.SH DESCRIPTION +.sp +\fBunbound\-anchor\fP performs setup or update of the root trust anchor for DNSSEC +validation. +The program fetches the trust anchor with the method from \fI\%RFC 7958\fP when +regular \fI\%RFC 5011\fP 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 +scripts. +Before you start the \fI\%unbound(8)\fP DNS server. +.sp Suggested usage: -.P +.INDENT 0.0 +.INDENT 3.5 +.sp .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 +.ft C +# in the init scripts. +# provide or update the root anchor (if necessary) +unbound\-anchor \-a \(dq@UNBOUND_ROOTKEY_FILE@\(dq +# 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: \(dq@UNBOUND_ROOTKEY_FILE@\(dq +unbound \-c unbound.conf +.ft P .fi -.P -This tool provides builtin default contents for the root anchor and root -update certificate files. -.P +.UNINDENT +.UNINDENT +.sp +This tool provides builtin default contents for the root anchor and root update +certificate files. +.sp 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 +It performs a https fetch of +\fI\%root\-anchors.xml\fP +and checks the results (\fI\%RFC 7958\fP); if all checks are successful, it updates +the root anchor file. +Otherwise the root anchor file is unchanged. +It performs \fI\%RFC 5011\fP tracking if the DNSSEC information available via the +DNS makes that possible. +.sp +It does not perform an update if the certificate is expired, if the network is +down or other errors occur. +.sp The available options are: +.INDENT 0.0 .TP -.B \-a \fIfile +.B \-a <file> 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. +Default is \fB@UNBOUND_ROOTKEY_FILE@\fP\&. +If the file does not exist, or is empty, a builtin root key is written +to it. +.UNINDENT +.INDENT 0.0 .TP -.B \-c \fIfile +.B \-c <file> The root update certificate file, that is read in. -Default is @UNBOUND_ROOTCERT_FILE@. +Default is \fB@UNBOUND_ROOTCERT_FILE@\fP\&. If the file does not exist, or is empty, a builtin certificate is used. +.UNINDENT +.INDENT 0.0 .TP .B \-l List the builtin root key and builtin root update certificate on stdout. +.UNINDENT +.INDENT 0.0 .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. +.B \-u <name> +The server name, it connects to \fBhttps://name\fP\&. +Specify without \fBhttps://\fP prefix. +The default is \fB\(dqdata.iana.org\(dq\fP\&. +It connects to the port specified with \fI\%\-P\fP\&. You can pass an IPv4 address or IPv6 address (no brackets) if you want. +.UNINDENT +.INDENT 0.0 .TP .B \-S -Do not use SNI for the HTTPS connection. Default is to use SNI. +Do not use SNI for the HTTPS connection. +Default is to use SNI. +.UNINDENT +.INDENT 0.0 .TP -.B \-b \fIaddress -The source address to bind to for domain resolution and contacting the server -on https. May be either an IPv4 address or IPv6 address (no brackets). +.B \-b <address> +The source address to bind to for domain resolution and contacting the +server on https. +May be either an IPv4 address or IPv6 address (no brackets). +.UNINDENT +.INDENT 0.0 .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. +.B \-x <path> +The pathname to the root\-anchors.xml file on the server. +(forms URL with \fI\%\-u\fP). +The default is \fB/root\-anchors/root\-anchors.xml\fP\&. +.UNINDENT +.INDENT 0.0 .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. +.B \-s <path> +The pathname to the root\-anchors.p7s file on the server. +(forms URL with \fI\%\-u\fP). +The default is \fB/root\-anchors/root\-anchors.p7s\fP\&. +This file has to be a PKCS7 signature over the xml file, using the pem +file (\fI\%\-c\fP) as trust anchor. +.UNINDENT +.INDENT 0.0 .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. +.B \-n <name> +The emailAddress for the Subject of the signer\(aqs certificate from the +p7s signature file. +Only signatures from this name are allowed. +The default is \fBdnssec@iana.org\fP\&. +If you pass \fB\(dq\(dq\fP then the emailAddress is not checked. +.UNINDENT +.INDENT 0.0 .TP .B \-4 -Use IPv4 for domain resolution and contacting the server on https. Default is -to use IPv4 and IPv6 where appropriate. +Use IPv4 for domain resolution and contacting the server on +https. +Default is to use IPv4 and IPv6 where appropriate. +.UNINDENT +.INDENT 0.0 .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. +Use IPv6 for domain resolution and contacting the server on https. +Default is to use IPv4 and IPv6 where appropriate. +.UNINDENT +.INDENT 0.0 +.TP +.B \-f <resolv.conf> +Use the given resolv.conf file. +Not enabled by default, but you could try to pass +\fB/etc/resolv.conf\fP 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. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r <root.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 (\fI\%\-u\fP 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. +resolver, cannot use that recursive resolver itself because it is +bootstrapping that server. +.UNINDENT +.INDENT 0.0 .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. +Allow fallback from \fI\%\-f\fP \fB<resolv.conf>\fP 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. +.UNINDENT +.INDENT 0.0 .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. +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. +.UNINDENT +.INDENT 0.0 .TP -.B \-C \fIunbound.conf -Debug option to read unbound.conf into the resolver process used. +.B \-C <unbound.conf> +Debug option to read \fB<unbound.conf>\fP into the resolver process +used. +.UNINDENT +.INDENT 0.0 .TP -.B \-P \fIport -Set the port number to use for the https connection. The default is 443. +.B \-P <port> +Set the port number to use for the https connection. +The default is 443. +.UNINDENT +.INDENT 0.0 .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. +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. +.UNINDENT +.INDENT 0.0 .TP .B \-h Show the version and commandline option help. -.SH "EXIT CODE" +.UNINDENT +.SH EXIT CODE +.sp 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 +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 \fI\%RFC 5011\fP tracking, or if an error occurred. +.sp You can check the exit value in this manner: +.INDENT 0.0 +.INDENT 3.5 +.sp .nf - unbound-anchor \-a "root.key" || logger "Please check root.key" +.ft C +unbound\-anchor \-a \(dqroot.key\(dq || logger \(dqPlease check root.key\(dq +.ft P .fi +.UNINDENT +.UNINDENT +.sp 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 -https://github.com/NLnetLabs/unbound/blob/master/LICENSE) and might be stale or -not suitable to your purpose. -.P -By running "unbound\-anchor \-l" the keys and certificate that are +.SH TRUST +.sp +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 \fI\%https://github.com/NLnetLabs/unbound/blob/master/LICENSE\fP +and might be stale or not suitable to your purpose. +.sp +By running \fI\%unbound\-anchor \-l\fP 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" +.sp +The built\-in configuration can be overridden by providing a root\-cert file and +a rootkey file. +.SH FILES +.INDENT 0.0 .TP -.I @UNBOUND_ROOTKEY_FILE@ -The root anchor file, updated with 5011 tracking, and read and written to. +.B @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). +.B @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 +\fI\%https://data.iana.org/root\-anchors/icannbundle.pem\fP (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 +.B \fI\%https://data.iana.org/root\-anchors/root\-anchors.xml\fP Source for the root key information. .TP -.I https://data.iana.org/root\-anchors/root\-anchors.p7s +.B \fI\%https://data.iana.org/root\-anchors/root\-anchors.p7s\fP Signature on the root key information. -.SH "SEE ALSO" -\fIunbound.conf\fR(5), -\fIunbound\fR(8). +.UNINDENT +.SH SEE ALSO +.sp +\fI\%unbound.conf(5)\fP, +\fI\%unbound(8)\fP\&. +.SH AUTHOR +Unbound developers are mentioned in the CREDITS file in the distribution. +.SH COPYRIGHT +1999-2025, NLnet Labs +.\" Generated by docutils manpage writer. +. |