man: add footnote explaining why "localhost" query is sent out to the network

I tried to make the explanation brief, but this isn't so easy. It seems better
to push this out to a footnote instead of the main text.

Fixes #16584.

1 files changed, 20 insertions, 5 deletions

diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml
index e6bfdf938b..ed6214cd62 100644
--- a/man/systemd-resolved.service.xml
+++ b/man/systemd-resolved.service.xml
@@ -115,8 +115,8 @@
   <refsect1>
     <title>Protocols and Routing</title>
 
-    <para>Lookup requests are routed to the available DNS servers, LLMNR, and MulticastDNS interfaces
-    according to the following rules:</para>
+    <para>The lookup requests that <filename>systemd-resolved.service</filename> receives are routed to the
+    available DNS servers, LLMNR, and MulticastDNS interfaces according to the following rules:</para>
 
     <itemizedlist>
       <listitem><para>Names for which synthetic records are generated (the local hostname,
@@ -172,7 +172,8 @@
     <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a
     description of globally configured DNS settings.</para>
 
-    <para>The following query routing logic applies for unicast DNS traffic:</para>
+    <para>The following query routing logic applies for unicast DNS lookups initiated by
+    <filename>systemd-resolved.service</filename>:</para>
 
     <itemizedlist>
       <listitem><para>If a name to look up matches (that is: is equal to or has as suffix) any of the
@@ -228,8 +229,22 @@
 
     <itemizedlist>
       <listitem><para>Some names are always resolved internally (see Synthetic Records above). Traditionally
-      they would be resolved by <filename>nss-files</filename>, and only if provided in
-      <filename>/etc/hosts</filename>.</para></listitem>
+      they would be resolved by <filename>nss-files</filename> if provided in
+      <filename>/etc/hosts</filename>. But note that the details of how a query is constructed are under the
+      control of the client library. <filename>nss-dns</filename> will first try to resolve names using
+      search domains and even if those queries are routed to <filename>systemd-resolved</filename>, it will
+      send them out over the network using the usual rules for multi-label name routing <footnote><para>For
+      example, if <filename>/etc/nsswitch.conf</filename> has <programlisting>nameserver 127.0.0.53
+search foobar.com barbar.com
+      </programlisting>and we look up <literal>localhost</literal>, <filename>nss-dns</filename> will send
+      the following queries to <filename>systemd-resolved</filename> listening on 127.0.0.53:53: first
+      <literal>localhost.foobar.com</literal>, then <literal>localhost.barbar.com</literal>, and finally
+      <literal>localhost</literal>. If (hopefully) the first two queries fail,
+      <filename>systemd-resolved</filename> will synthesize an answer for the third query.</para>
+
+      <para>When using <filename>nss-dns</filename> with any search domains, it is thus crucial to always
+      configure <filename>nss-files</filename> with higher priority and provide mappings for names that
+      should not be resolved using search domains.</para></footnote>.</para></listitem>
 
       <listitem><para>Single-label names are not resolved for A and AAAA records using unicast DNS (unless
       overridden with <varname>ResolveUnicastSingleLabel=</varname>, see