From b541146bf8c34aaaa9efcf58325f18da9253c4ec Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 21 Jun 2016 13:19:21 +0200 Subject: [PATCH] man: beef up resolved man page Let's explain the various APIs and various ways to handle /etc/resolv.conf. --- man/systemd-resolved.service.xml | 91 ++++++++++++++++++++++++-------- 1 file changed, 70 insertions(+), 21 deletions(-) diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 485f3e9aee..0df037ba69 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. + responder. Local applications may submit network name resolution requests via three interfaces: - The glibc NSS module - nss-resolve8 is required to - permit glibc's NSS resolver functions to resolve host names via systemd-resolved. + + 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 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). + 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. - systemd-resolved synthesizes DNS RRs for the following cases: + 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. + + + 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. + + <filename>/etc/resolv.conf</filename> + + 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