diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml
index 485f3e9aee414..0df037ba69ffa 100644
--- a/man/systemd-resolved.service.xml
+++ b/man/systemd-resolved.service.xml
@@ -58,27 +58,45 @@
systemd-resolved is a system service that provides network name resolution to local
applications. It implements a caching and validating DNS/DNSSEC stub resolver, as well as an LLMNR resolver and
- responder. In addition it maintains the /run/systemd/resolve/resolv.conf file for
- compatibility with traditional Linux programs. This file may be symlinked from
- /etc/resolv.conf.
-
- The glibc NSS module
- nss-resolve8 is required to
- permit glibc's NSS resolver functions to resolve host names via systemd-resolved.
-
- The DNS servers contacted are determined from the global
- settings in /etc/systemd/resolved.conf, the
- per-link static settings in /etc/systemd/network/*.network files,
- and the per-link dynamic settings received over DHCP. See
- resolved.conf5
- and
- systemd.network5
- for details. To improve compatibility,
- /etc/resolv.conf is read in order to discover
- configured system DNS servers, but only if it is not a symlink
- to /run/systemd/resolve/resolv.conf (see above).
+ responder. Local applications may submit network name resolution requests via three interfaces:
+
+
+ The native, fully-featured API systemd-resolved exposes on the bus. See the
+ API Documentation for
+ details. Usage of this API is generally recommended to clients as it is asynchronous and fully featured (for
+ example, properly returns DNSSEC validation status and interface scope for addresses as necessary for supporting
+ link-local networking).
+
+ The glibc
+ getaddrinfo3 API (as defined
+ by RFC3493) and its related resolver functions,
+ including gethostbyname3. This
+ API is widely supported, including beyond the Linux platform. In its current form it does not expose DNSSEC
+ validation status information however, and is synchronous only. This API is backed by the glibc Name Service
+ Switch (nss5). Usage of the
+ glibc NSS module nss-resolve8
+ is required in order to allow glibc's NSS resolver functions to resolve host names via
+ systemd-resolved.
+
+ Additionally, systemd-resolved provides a local DNS stub listener on IP
+ address 127.0.0.53 on the local loopback interface. Programs issuing DNS requests directly, bypassing any local
+ API may be directed to this stub, in order to connect them systemd-resolved. Note however that
+ it is strongly recommended that local programs use the glibc NSS or bus APIs instead (as described above), as
+ various network resolution concepts (such as link-local addressing, or LLMNR Unicode domains) cannot be mapped to
+ the unicast DNS protocol.
+
- systemd-resolved synthesizes DNS RRs for the following cases:
+ The DNS servers contacted are determined from the global settings in
+ /etc/systemd/resolved.conf, the per-link static settings in
+ /etc/systemd/network/*.network files, the per-link dynamic settings received over DHCP and any
+ DNS server information made available by other system services. See
+ resolved.conf5 and
+ systemd.network5 for details
+ about systemd's own configuration files for DNS servers. To improve compatibility,
+ /etc/resolv.conf is read in order to discover configured system DNS servers, but only if it is
+ not a symlink to /run/systemd/resolve/resolv.conf (see below).
+
+ systemd-resolved synthesizes DNS resource records (RRs) for the following cases:
The local, configured hostname is resolved to
@@ -137,14 +155,45 @@
per-interface domains are exclusively routed to the matching
interfaces.
- Note that /run/systemd/resolve/resolv.conf should not be used directly by applications,
- but only through a symlink from /etc/resolv.conf.
-
See the resolved D-Bus API
Documentation for information about the APIs systemd-resolved provides.
+
+ /etc/resolv.conf
+
+ Three modes of handling /etc/resolv.conf (see
+ resolv.conf5) are
+ supported:
+
+
+ A static file /usr/lib/systemd/resolv.conf is provided that lists
+ the 127.0.0.53 DNS stub (see above) as only DNS server. This file may be symlinked from
+ /etc/resolv.conf in order to connect all local clients that bypass local DNS APIs to
+ systemd-resolved. This mode of operation is recommended.
+
+ systemd-resolved maintains the
+ /run/systemd/resolve/resolv.conf file for compatibility with traditional Linux
+ programs. This file may be symlinked from /etc/resolv.conf and is always kept up-to-date,
+ containing information about all known DNS servers. Note the file format's limitations: it does not know a
+ concept of per-interface DNS servers and hence only contains system-wide DNS server definitions. Note that
+ /run/systemd/resolve/resolv.conf should not be used directly by applications, but only
+ through a symlink from /etc/resolv.conf. If this mode of operation is used local clients
+ that bypass any local DNS API will also bypass systemd-resolved and will talk directly to the
+ known DNS servers.
+
+ Alternatively, /etc/resolv.conf may be managed by other packages, in which
+ case systemd-resolved will read it for DNS configuration data. In this mode of operation
+ systemd-resolved is consumer rather than provider of this configuration
+ file.
+
+
+ Note that the selected mode of operation for this file is detected fully automatically, depending on whether
+ /etc/resolv.conf is a symlink to /run/systemd/resolve/resolv.conf or
+ lists 127.0.0.53 as DNS server.
+
+
Signals