- 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 2712544d771a77da942c11a344fd30280c12d5c9..a39a1d800d1d09d5e6642b3cec6589776671f7ab 100644 (file)
--- 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 9c77b4cf7692dbb237aa80378ad0e4297b573f63..5c8c02fef415fa15a0cb0a9407c0c07d273f0582 100644 (file)
--- 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 480db8eeb8c958ac826e6b32bbb5757e3629f4b2..fec351a973fe5fbf0e9953f1e6a7e85d1b4c8907 100644 (file)
--- 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)</manpages/unbound>` DNS server.
+It can be run from the commandline, or run as part of startup scripts before
+you start the :doc:`unbound(8)</manpages/unbound>` DNS server.
+
+Note that if you want to use :rfc:`5011` with Unbound (i.e., the
+:ref:`auto-trust-anchor-file<unbound.conf.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 1a216d9b3cccfa426f33e02ddf8dff352f4c4dcf..d87b96c226f4539b3380217d070cb3c7dfb14243 100644 (file)
--- 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<yes or no>\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