- 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.

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

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

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>*

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 "

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 "