networkd: rework Domains= setting

Previously, .network files only knew a vaguely defined "Domains=" concept, for which the documentation declared it was
the "DNS domain" for the network connection, without specifying what that means.

With this the Domains setting is reworked, so that there are now "routing" domains and "search" domains. The former are
to be used by resolved to route DNS request to specific network interfaces, the latter is to be used for searching
single-label hostnames with (in addition to being used for routing). Both settings are configured in the "Domains="
setting. Normal domain names listed in it are now considered search domains (for compatibility with existing setups),
while those prefixed with "~" are considered routing domains only. To route all lookups to a specific interface the
routing domain "." may be used, referring to the root domain. An alternative syntax for this is the "*", as was already
implemented before using the "wildcard" domain concept.

This commit adds proper parsers for this new logic, and exposes this via the sd-network API. This information is not
used by resolved yet, this will be added in a later commit.

1 files changed, 20 insertions, 4 deletions

diff --git a/man/systemd.network.xml b/man/systemd.network.xml
index 5a6383cfc2..be88d66072 100644
--- a/man/systemd.network.xml
+++ b/man/systemd.network.xml
@@ -396,21 +396,37 @@
             described in
             <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
             This option may be specified more than once. This setting is read by
-            <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></para>
+            <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term><varname>Domains=</varname></term>
           <listitem>
-            <para>The domains used for DNS resolution over this link. This setting is read by
-            <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></para>
+            <para>The domains used for DNS host name resolution on this link. Takes a list of DNS domain names which
+            are used as search suffixes for extending single-label host names (host names containing no dots) to become
+            fully qualified domain names (FQDNs). If a single-label host name is resolved on this interface, each of
+            the specified search domains are appended to it in turn, converting it into a fully qualified domain name,
+            until one of them may be successfully resolved.</para>
+
+            <para>The specified domains are also used for routing of DNS queries: look-ups for host names ending in the
+            domains specified here are preferably routed to the DNS servers configured for this interface. If a domain
+            name is prefixed with <literal>~</literal>, the domain name becomes a pure "routing" domain, is used for
+            DNS query routing purposes only and is not used in the described domain search logic. By specifying a
+            routing domain of <literal>~.</literal> (the tilda indicating definition of a routing domain, the dot
+            referring to the DNS root domain which is the implied suffix of all valid DNS names) it is possible to
+            route all DNS traffic preferably to the DNS server specified for this interface. The route domain logic is
+            particularly useful on multi-homed hosts with DNS servers serving particular private DNS zones on each
+            interface.</para>
+
+            <para>This setting is read by
+            <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term><varname>NTP=</varname></term>
           <listitem>
             <para>An NTP server address. This option may be specified more than once. This setting is read by
-            <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></para>
+            <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
           </listitem>
         </varlistentry>
         <varlistentry>