The lookup requests that systemd-resolved.service receives are
routed to the available DNS servers, LLMNR, and MulticastDNS
interfaces according to the following rules:
• Names for which synthetic records are generated (the local
hostname, "localhost" and "localdomain", local gateway, as
listed in the previous section) and addresses configured in
/etc/hosts are never routed to the network and a reply is
sent immediately.
• Single-label names are resolved using LLMNR on all local
interfaces where LLMNR is enabled. Lookups for IPv4 addresses
are only sent via LLMNR on IPv4, and lookups for IPv6
addresses are only sent via LLMNR on IPv6. Note that lookups
for single-label synthesized names are not routed to LLMNR,
MulticastDNS or unicast DNS.
• Queries for the address records (A and AAAA) of single-label
non-synthesized names are resolved via unicast DNS using
search domains. For any interface which defines search
domains, such look-ups are routed to the servers defined for
that interface, suffixed with each of those search domains.
When global search domains are defined, such look-ups are
routed to the global servers. For each search domain, queries
are performed by suffixing the name with each of the search
domains in turn. Additionally, lookup of single-label names
via unicast DNS may be enabled with the
ResolveUnicastSingleLabel=yes 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 resolution is only possible if search
domains are defined.
• Multi-label names with the domain suffix ".local" are
resolved using MulticastDNS on all local interfaces where
MulticastDNS is enabled. As with LLMNR, IPv4 address lookups
are sent via IPv4 and IPv6 address lookups are sent via IPv6.
• Queries for multi-label names are routed via unicast DNS on
local interfaces that have a DNS server configured, plus the
globally configured DNS servers if there are any. Which
interfaces are used is determined by the routing logic based
on search and route-only domains, described below. Note that
by default, lookups for domains with the ".local" suffix are
not routed to DNS servers, unless the domain is specified
explicitly as routing or search domain for the DNS server and
interface. This means that on networks where the ".local"
domain is defined in a site-specific DNS server, explicit
search or routing domains need to be configured to make
lookups work within this DNS domain. Note that these days,
it's generally recommended to avoid defining ".local" in a
DNS server, as RFC6762
• Address lookups (reverse lookups) are routed similarly to
multi-label names, with the exception that addresses from the
link-local address range are never routed to unicast DNS and
are only resolved using LLMNR and MulticastDNS (when
enabled).
If lookups are routed to multiple interfaces, the first
successful response is returned (thus effectively merging the
lookup zones on all matching interfaces). If the lookup failed on
all interfaces, the last failing response is returned.
Routing of lookups is determined by the per-interface routing
domains (search and route-only) and global search domains. See
systemd.network(5) and resolvectl(1) for a description how those
settings are set dynamically and the discussion of Domains= in
resolved.conf(5) for a description of globally configured DNS
settings.
The following query routing logic applies for unicast DNS lookups
initiated by systemd-resolved.service:
• If a name to look up matches (that is: is equal to or has as
suffix) any of the configured routing domains (search or
route-only) of any link, or the globally configured DNS
settings, "best matching" routing domain is determined: the
matching one with the most labels. The query is then sent to
all DNS servers of any links or the globally configured DNS
servers associated with this "best matching" routing domain.
(Note that more than one link might have this same "best
matching" routing domain configured, in which case the query
is sent to all of them in parallel).
In case of single-label names, when search domains are
defined, the same logic applies, except that the name is
first suffixed by each of the search domains in turn. Note
that this search logic doesn't apply to any names with at
least one dot. Also see the discussion about compatibility
with the traditional glibc resolver below.
• If a query does not match any configured routing domain
(either per-link or global), it is sent to all DNS servers
that are configured on links with the DefaultRoute= option
set, as well as the globally configured DNS server.
• If there is no link configured as DefaultRoute= and no global
DNS server configured, one of the compiled-in fallback DNS
servers is used.
• Otherwise the unicast DNS query fails, as no suitable DNS
servers can be determined.
The DefaultRoute= option is a boolean setting configurable with
resolvectl or in .network files. If not set, it is implicitly
determined based on the configured DNS domains for a link: if
there's a route-only domain other than "~.", it defaults to
false, otherwise to true.
Effectively this means: in order to support single-label
non-synthesized names, define appropriate search domains. In
order to preferably route all DNS queries not explicitly matched
by routing domain configuration to a specific link, configure a
"~." route-only domain on it. This will ensure that other links
will not be considered for these queries (unless they too carry
such a routing domain). In order to route all such DNS queries to
a specific link only if no other link is preferred, set the
DefaultRoute= option for the link to true and do not configure a
"~." route-only domain on it. Finally, in order to ensure that a
specific link never receives any DNS traffic not matching any of
its configured routing domains, set the DefaultRoute= option for
it to false.
See org.freedesktop.resolve1(5) for information about the D-Bus
APIs systemd-resolved provides.
