man: document the new option

Also correct "stub resolver" → "systemd-resolved" in one other option.

diff --git a/NEWS b/NEWS
index b27d38be77052ce98cbdd714d11f1781c0688d2e..da9402867ebd0a9af8578b96eb0ecd539f57df5f 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -87,6 +87,12 @@ CHANGES WITH 246 in spe:
           used, the DNS-over-TLS certificate is validated to match the
           specified hostname.
 
+        * systemd-resolved may be configured to forward single-label DNS names.
+          This is not standard-conformant, but may make sense in setups where
+          public DNS servers are not used.
+
+        * systemd-resolved's DNS-over-TLS support gained SNI validation.
+
         * The fs.suid_dumpable sysctl is set to 2 / "suidsafe". This allows
           systemd-coredump to save core files for suid processes. When saving
           the core file, systemd-coredump will use the effective uid and gid of
@@ -528,8 +534,6 @@ CHANGES WITH 245:
         * systemd-sysusers gained support for creating users with the primary
           group named differently than the user.
 
-        * systemd-resolved's DNS-over-TLS support gained SNI validation.
-
         * systemd-growfs (i.e. the x-systemd.growfs mount option in /etc/fstab)
           gained support for growing XFS partitions. Previously it supported
           only ext4 and btrfs partitions.

diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml
index 33265f755cb0c380410c4a5ee2ca0743258bc2b6..0e9b90c1cd9c375b23a1c119b9398564d230128c 100644 (file)
--- a/man/resolved.conf.xml
+++ b/man/resolved.conf.xml
@@ -266,11 +266,28 @@
 
       <varlistentry>
         <term><varname>ReadEtcHosts=</varname></term>
-        <listitem><para>Takes a boolean argument. If <literal>yes</literal> (the default), the DNS stub resolver will read
-        <filename>/etc/hosts</filename>, and try to resolve hosts or address by using the entries in the file before
-        sending query to DNS servers.</para></listitem>
+        <listitem><para>Takes a boolean argument. If <literal>yes</literal> (the default),
+        <command>systemd-resolved</command> will read <filename>/etc/hosts</filename>, and try to resolve
+        hosts or address by using the entries in the file before sending query to DNS servers.
+        </para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>ResolveUnicastSingleLabel=</varname></term>
+        <listitem><para>Takes a boolean argument. When false (the default),
+        <command>systemd-resolved</command> will not resolve A and AAAA queries for single-label names over
+        classic DNS. Note that such names may still be resolved if search domains are specified (see
+        <varname>Domains=</varname> above), or using other mechanisms, in particular via LLMNR or from
+        <filename>/etc/hosts</filename>. When true, queries for single-label names will be forwarded to
+        global DNS servers even if no search domains are defined.
+        </para>
+
+        <para>This option is provided for compatibility with configurations where <emphasis>public DNS
+        servers are not used</emphasis>. Forwarding single-label names to servers not under your control is
+        not standard-conformant, see <ulink
+        url="https://www.iab.org/documents/correspondence-reports-documents/2013-2/iab-statement-dotless-domains-considered-harmful/">IAB
+        Statement</ulink>, and may create a privacy and security risk.</para></listitem>
+      </varlistentry>
     </variablelist>
   </refsect1>
 

diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml
index 6e1ee9f4a5158229561b579277944d10ce90d49a..914607e3f8d621827dec247c19eac3144fb3a757 100644 (file)
--- a/man/systemd-resolved.service.xml
+++ b/man/systemd-resolved.service.xml
@@ -135,14 +135,16 @@
       IPv6.</para></listitem>
 
       <listitem><para>Resolution of address records (A and AAAA) via unicast DNS (i.e. not LLMNR or
-      MulticastDNS) for non-synthesized single-label names is only allowed for non-top-level domains. This
-      means that such records can only be resolved when search domains are defined. For any interface which
-      defines search domains, such look-ups are routed to that interface, suffixed with each of the search
-      domains defined on that interface in turn. When global search domains are defined, such look-ups are
-      routed to all interfaces, suffixed by each of the global search domains in turn. The details of which
-      servers are queried and how the final reply is chosen are described below. Note that this means that
-      address queries for single-label names are never sent out to remote DNS servers, and if no search
-      domains are defined, resolution will fail.</para></listitem>
+      MulticastDNS) for non-synthesized single-label names is allowed for non-top-level domains. This means
+      that such records can be resolved when search domains are defined. For any interface which defines
+      search domains, such look-ups are routed to that interface, suffixed with each of the search domains
+      defined on that interface in turn. When global search domains are defined, such look-ups are routed to
+      all interfaces, suffixed by each of the global search domains in turn. Additionally, lookup of
+      single-label names via unicast DNS may be enabled with the
+      <varname>ResolveUnicastSingleLabel=yes</varname> setting. The details of which servers are queried and
+      how the final reply is chosen are described below. Note that this means that address queries for
+      single-label names are never sent out to remote DNS servers by default, and if no search domains are
+      defined, resolution will fail.</para></listitem>
 
       <listitem><para>Other multi-label names are routed to all local interfaces that have a DNS server
       configured, plus the globally configured DNS servers if there are any. Note that by default, lookups for