- Fix #1165, document the possible circular dependency when using

  host names instead of IP addresses for name servers in stub/forward
  zones and log a warning when spotted in the configuration.

diff --git a/doc/Changelog b/doc/Changelog
index f52cde5700d45d5f5a1022e1055bf90f58028c61..3a8506e61bfb850e60047856bf3fe6ddbcc79821 100644 (file)
--- a/doc/Changelog
+++ b/doc/Changelog
@@ -1,6 +1,9 @@
 27 October 2025: Yorgos
        - Merge #1331 from Jitka Plesníková: Replace deprecated $function by
          new $action, for SWIG.
+       - Fix #1165, document the possible circular dependency when using
+         host names instead of IP addresses for name servers in stub/forward
+         zones and log a warning when spotted in the configuration.
 
 24 October 2025: Yorgos
        - unbound.conf man page updates to include a preview of the section

diff --git a/doc/unbound.conf.5.in b/doc/unbound.conf.5.in
index f4b71bd14fee0e4b0301bf56166de56f0e6316be..1a216d9b3cccfa426f33e02ddf8dff352f4c4dcf 100644 (file)
--- a/doc/unbound.conf.5.in
+++ b/doc/unbound.conf.5.in
@@ -4075,6 +4075,23 @@ This is the full domain name of the zone.
 Name of stub zone nameserver.
 Is itself resolved before it is used.
 .sp
+\fBCAUTION:\fP
+.INDENT 7.0
+.INDENT 3.5
+If the domain (or a subdomain) from this zone is used as the host, it
+will unavoidably introduce a circular dependency on retrieving the IP
+addresses of the name server.
+In that case, it is suggested to use
+\fI\%stub\-addr\fP instead.
+Alternatively,
+\fI\%stub\-first: yes\fP can also work
+around the circular dependency by trying resolution outside of this
+zone.
+However this has the caveat that it would allow escaping this zone when
+any resolution attempt fails within this zone.
+.UNINDENT
+.UNINDENT
+.sp
 To use a non\-default port for DNS communication append \fB\(aq@\(aq\fP with the
 port number.
 .sp
@@ -4185,6 +4202,23 @@ This is the full domain name of the zone.
 Name of server to forward to.
 Is itself resolved before it is used.
 .sp
+\fBCAUTION:\fP
+.INDENT 7.0
+.INDENT 3.5
+If the domain (or a subdomain) from this zone is used as the host, it
+will unavoidably introduce a circular dependency on retrieving the IP
+addresses of the name server.
+In that case, it is suggested to use
+\fI\%forward\-addr\fP instead.
+Alternatively,
+\fI\%forward\-first: yes\fP can also
+work around the circular dependency by trying resolution outside of
+this zone.
+However this has the caveat that it would allow escaping this zone when
+any resolution attempt fails within this zone.
+.UNINDENT
+.UNINDENT
+.sp
 To use a non\-default port for DNS communication append \fB\(aq@\(aq\fP with the
 port number.
 .sp

diff --git a/doc/unbound.conf.rst b/doc/unbound.conf.rst
index ba908fb23e22eb87aae5073ee976d2a96291fa56..8f78fb31d60ce1bdc596e4144356d61587355799 100644 (file)
--- a/doc/unbound.conf.rst
+++ b/doc/unbound.conf.rst
@@ -3534,6 +3534,19 @@ The :ref:`local-zone: nodefault<unbound.conf.local-zone.type.nodefault>` (or
     Name of stub zone nameserver.
     Is itself resolved before it is used.
 
+    .. caution::
+        If the domain (or a subdomain) from this zone is used as the host, it
+        will unavoidably introduce a circular dependency on retrieving the IP
+        addresses of the name server.
+        In that case, it is suggested to use
+        :ref:`stub-addr<unbound.conf.stub.stub-addr>` instead.
+        Alternatively,
+        :ref:`stub-first: yes<unbound.conf.stub.stub-first>` can also work
+        around the circular dependency by trying resolution outside of this
+        zone.
+        However this has the caveat that it would allow escaping this zone when
+        any resolution attempt fails within this zone.
+
     To use a non-default port for DNS communication append ``'@'`` with the
     port number.
 
@@ -3639,6 +3652,19 @@ cache).
     Name of server to forward to.
     Is itself resolved before it is used.
 
+    .. caution::
+        If the domain (or a subdomain) from this zone is used as the host, it
+        will unavoidably introduce a circular dependency on retrieving the IP
+        addresses of the name server.
+        In that case, it is suggested to use
+        :ref:`forward-addr<unbound.conf.forward.forward-addr>` instead.
+        Alternatively,
+        :ref:`forward-first: yes<unbound.conf.forward.forward-first>` can also
+        work around the circular dependency by trying resolution outside of
+        this zone.
+        However this has the caveat that it would allow escaping this zone when
+        any resolution attempt fails within this zone.
+
     To use a non-default port for DNS communication append ``'@'`` with the
     port number.
 
@@ -3786,9 +3812,11 @@ fallback activates to fetch from the upstream instead of the SERVFAIL.
     :ref:`url<unbound.conf.auth.url>` to download the zonefile as a text file
     from a webserver that would work.
 
-    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.
+    .. caution::
+        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.
 
 
 @@UAHL@unbound.conf.auth@master@@: *<IP address or host name>*

diff --git a/iterator/iter_fwd.c b/iterator/iter_fwd.c
index 5d70c6664862341b5e9d7d97f38c2876b3d38541..e5991ac3e1dc5ec30dcdebff67f69c1fe9d5f4b0 100644 (file)
--- a/iterator/iter_fwd.c
+++ b/iterator/iter_fwd.c
@@ -228,6 +228,11 @@ read_fwds_host(struct config_stub* s, struct delegpt* dp)
                                s->name, p->str);
                        return 0;
                }
+               if(dname_subdomain_c(dname, dp->name)) {
+                       log_warn("forward-host '%s' may have has a circular "
+                               "dependency on forward-zone '%s'",
+                               p->str, s->name);
+               }
 #if ! defined(HAVE_SSL_SET1_HOST) && ! defined(HAVE_X509_VERIFY_PARAM_SET1_HOST)
                if(tls_auth_name)
                        log_err("no name verification functionality in "

diff --git a/iterator/iter_hints.c b/iterator/iter_hints.c
index 9faf155ababe22ec8c24a3076144f607860e21b8..a1fc86f58cbcc2fdc515c4748ce07b982c756c51 100644 (file)
--- a/iterator/iter_hints.c
+++ b/iterator/iter_hints.c
@@ -231,6 +231,11 @@ read_stubs_host(struct config_stub* s, struct delegpt* dp)
                                s->name, p->str);
                        return 0;
                }
+               if(dname_subdomain_c(dname, dp->name)) {
+                       log_warn("stub-host '%s' may have a circular "
+                               "dependency on stub-zone '%s'",
+                               p->str, s->name);
+               }
 #if ! defined(HAVE_SSL_SET1_HOST) && ! defined(HAVE_X509_VERIFY_PARAM_SET1_HOST)
                if(tls_auth_name)
                        log_err("no name verification functionality in "