diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml
index 32512fd6275..8f3494e36b0 100644
--- a/man/systemd-resolved.service.xml
+++ b/man/systemd-resolved.service.xml
@@ -183,7 +183,9 @@
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.
+ 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 compatiblity 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=
@@ -216,6 +218,63 @@
for information about the D-Bus APIs systemd-resolved provides.
+
+ Compatibility with the traditional glibc stub resolver
+
+ This section provides a short summary of differences in the stub resolver implemented by
+ nss-resolve8 together
+ with systemd-resolved and the tranditional stub resolver implemented in
+ nss-dns8.
+
+
+ Some names are always resolved internally (see Synthetic Records above). Traditionally
+ they would be resolved by nss-files, and only if provided in
+ /etc/hosts.
+
+ Single-label names are not resolved for A and AAAA records using unicast DNS (unless
+ overriden with ResolveUnicastSingleLabel=, see
+ resolved.conf5).
+ This is similar to the option being set in
+ resolv.conf5.
+
+
+ Search domains are not used for suffixing of multi-label names.
+ (Search domains are nevertheless used for lookup routing, for names that were
+ originally specified as single-label or multi-label.) Any name with at least one dot is always
+ interpreted as a FQDN. nss-dns would resolve names both as relative (using search
+ domains) and absolute FQDN names. Some names would be resolved as relative first, and after that query
+ has failed, as absolute, while other names would be resolved in opposite order. The
+ ndots option in /etc/resolv.conf was used to control how many
+ dots the name needs to have to be resolved as relative first. This stub resolver does not implement
+ this at all: multi-label names are only resolved as FQDNs. (There are currently more than 1500
+ top-level domain names defined, and new ones are added regularly, often using "attractive" names that
+ are also likely to be used locally. Not looking up multi-label names in this fashion avoids fragility
+ in both directions: a valid global name could be obscured by a local name, and resolution of a relative
+ local name could suddenly break when a new top-level domain is created, or when a new subdomain of a
+ top-level domain in registered. Resolving any given name as either relative or absolute avoids this
+ ambiguity.)
+
+ This resolver has a notion of the special .local domain used for
+ MulticastDNS, and will not route queries with that suffix to unicast DNS servers unless explicitly
+ configured, see above. Also, reverse lookups for link-local addresses are not sent to unicast DNS
+ servers.
+
+ This resolver reads and caches /etc/hosts internally. (In other
+ words, nss-resolve replaces nss-files in addition to
+ nss-dns). Entries in /etc/hosts have highest priority.
+
+
+ This resolver also implements LLMNR and MulticastDNS in addition to the classic unicast
+ DNS protocol, and will resolve single-label names using LLMNR (when enabled) and names ending in
+ .local using MulticastDNS (when enabled).
+
+ Environment variables $LOCALDOMAIN and
+ $RES_OPTIONS described in
+ resolv.conf5 are not
+ supported currently.
+
+
+
/etc/resolv.conf
@@ -302,7 +361,6 @@
synchronous way.
-