From: Yorgos Thessalonikefs Date: Wed, 31 Dec 2025 13:05:42 +0000 (+0100) Subject: - Update the unbound-anchor man page to note write permissions of the X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a1ac2d0252e273f48c9258f5bf15ae561e210ea2;p=thirdparty%2Funbound.git - Update the unbound-anchor man page to note write permissions of the generated file if it is to be used with Unbound's auto-trust-anchor-file option. --- diff --git a/doc/Changelog b/doc/Changelog index 2712544d7..a39a1d800 100644 --- a/doc/Changelog +++ b/doc/Changelog @@ -1,3 +1,8 @@ +31 December 2025: Yorgos + - Update the unbound-anchor man page to note write permissions of the + generated file if it is to be used with Unbound's + auto-trust-anchor-file option. + 30 December 2025: Yorgos - Mark "THROWAWAY" and "(DNSSEC) LAME" responses clearly as Unbound's categorization in the log output. diff --git a/doc/unbound-anchor.8.in b/doc/unbound-anchor.8.in index 9c77b4cf7..5c8c02fef 100644 --- a/doc/unbound-anchor.8.in +++ b/doc/unbound-anchor.8.in @@ -39,9 +39,17 @@ unbound-anchor \- Unbound @version@ anchor utility. 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 \fI\%unbound(8)\fP DNS server. +It can be run from the commandline, or run as part of startup scripts before +you start the \fI\%unbound(8)\fP DNS server. +.sp +Note that if you want to use \fI\%RFC 5011\fP with Unbound (i.e., the +\fI\%auto\-trust\-anchor\-file\fP option) so +that trust anchor information is automatically tracked by Unbound during +operation, the user that Unbound runs under (by default \(aqunbound\(aq) must have +write permissions to the file and the directory the file lives in (for creating +temporary files). +In this case you would probably want to run this program as the designated +Unbound user. .sp Suggested usage: .INDENT 0.0 @@ -52,6 +60,7 @@ Suggested usage: # 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). # diff --git a/doc/unbound-anchor.rst b/doc/unbound-anchor.rst index 480db8eeb..fec351a97 100644 --- a/doc/unbound-anchor.rst +++ b/doc/unbound-anchor.rst @@ -51,9 +51,17 @@ Description validation. The program fetches the trust anchor with the method from :rfc:`7958` when regular :rfc:`5011` 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 :doc:`unbound(8)` DNS server. +It can be run from the commandline, or run as part of startup scripts before +you start the :doc:`unbound(8)` DNS server. + +Note that if you want to use :rfc:`5011` with Unbound (i.e., the +:ref:`auto-trust-anchor-file` option) so +that trust anchor information is automatically tracked by Unbound during +operation, the user that Unbound runs under (by default 'unbound') must have +write permissions to the file and the directory the file lives in (for creating +temporary files). +In this case you would probably want to run this program as the designated +Unbound user. Suggested usage: @@ -62,6 +70,7 @@ Suggested usage: # 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). # diff --git a/doc/unbound.conf.5.in b/doc/unbound.conf.5.in index 1a216d9b3..d87b96c22 100644 --- a/doc/unbound.conf.5.in +++ b/doc/unbound.conf.5.in @@ -4135,6 +4135,9 @@ Default: no If enabled, a query is attempted without this stub section if it fails. The data could not be retrieved and would have caused SERVFAIL because the servers are unreachable, instead it is tried without this stub section. +This can lead to using less specific configured forward/stub/auth zones if +any, or end up to otherwise normal recursive resolution for that particular +query. .sp Default: no .UNINDENT @@ -4255,9 +4258,11 @@ The cert must also match a CA from the .INDENT 0.0 .TP .B forward\-first: \fI\fP -If a forwarded query is met with a SERVFAIL error, and this option is -enabled, Unbound will fall back to normal recursive resolution for this -query as if no query forwarding had been specified. +If a forwarded query is met with a SERVFAIL error and this option is +enabled Unbound will fall back to less specific resolution. +This can lead to using less specific configured forward/stub/auth zones if +any, or end up to otherwise normal recursive resolution for that particular +query. .sp Default: no .UNINDENT @@ -4370,9 +4375,15 @@ does not support AXFR/IXFR for the zone, but if you used \fI\%url\fP to download the zonefile as a text file from a webserver that would work. .sp -If you specify the hostname, you cannot use the domain from the zonefile, -because it may not have that when retrieving that data, instead use a plain -IP address to avoid a circular dependency on retrieving that IP address. +\fBCAUTION:\fP +.INDENT 7.0 +.INDENT 3.5 +If you specify the hostname, you cannot use the domain from the +zonefile, because it may not have that when retrieving that data, +instead use a plain IP address to avoid a circular dependency on +retrieving that IP address. +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP