1SYSTEMD-RESOLVED.SERVICE(8)systemd-resolved.serviceSYSTEMD-RESOLVED.SERVICE(8)
2
3
4

NAME

6       systemd-resolved.service, systemd-resolved - Network Name Resolution
7       manager
8

SYNOPSIS

10       systemd-resolved.service
11
12       /usr/lib/systemd/systemd-resolved
13

DESCRIPTION

15       systemd-resolved is a system service that provides network name
16       resolution to local applications. It implements a caching and
17       validating DNS/DNSSEC stub resolver, as well as an LLMNR and
18       MulticastDNS resolver and responder. Local applications may submit
19       network name resolution requests via three interfaces:
20
21       ·   The native, fully-featured API systemd-resolved exposes on the bus.
22           See the API Documentation[1] for details. Usage of this API is
23           generally recommended to clients as it is asynchronous and fully
24           featured (for example, properly returns DNSSEC validation status
25           and interface scope for addresses as necessary for supporting
26           link-local networking).
27
28       ·   The glibc getaddrinfo(3) API as defined by RFC3493[2] and its
29           related resolver functions, including gethostbyname(3). This API is
30           widely supported, including beyond the Linux platform. In its
31           current form it does not expose DNSSEC validation status
32           information however, and is synchronous only. This API is backed by
33           the glibc Name Service Switch (nss(5)). Usage of the glibc NSS
34           module nss-resolve(8) is required in order to allow glibc's NSS
35           resolver functions to resolve host names via systemd-resolved.
36
37       ·   Additionally, systemd-resolved provides a local DNS stub listener
38           on IP address 127.0.0.53 on the local loopback interface. Programs
39           issuing DNS requests directly, bypassing any local API may be
40           directed to this stub, in order to connect them to
41           systemd-resolved. Note however that it is strongly recommended that
42           local programs use the glibc NSS or bus APIs instead (as described
43           above), as various network resolution concepts (such as link-local
44           addressing, or LLMNR Unicode domains) cannot be mapped to the
45           unicast DNS protocol.
46
47       The DNS servers contacted are determined from the global settings in
48       /etc/systemd/resolved.conf, the per-link static settings in
49       /etc/systemd/network/*.network files (in case systemd-
50       networkd.service(8) is used), the per-link dynamic settings received
51       over DHCP, and any DNS server information made available by other
52       system services. See resolved.conf(5) and systemd.network(5) for
53       details about systemd's own configuration files for DNS servers. To
54       improve compatibility, /etc/resolv.conf is read in order to discover
55       configured system DNS servers, but only if it is not a symlink to
56       /run/systemd/resolve/stub-resolv.conf or
57       /run/systemd/resolve/resolv.conf (see below).
58
59       systemd-resolved synthesizes DNS resource records (RRs) for the
60       following cases:
61
62       ·   The local, configured hostname is resolved to all locally
63           configured IP addresses ordered by their scope, or — if none are
64           configured — the IPv4 address 127.0.0.2 (which is on the local
65           loopback) and the IPv6 address ::1 (which is the local host).
66
67       ·   The hostnames "localhost" and "localhost.localdomain" (as well as
68           any hostname ending in ".localhost" or ".localhost.localdomain")
69           are resolved to the IP addresses 127.0.0.1 and ::1.
70
71       ·   The hostname "_gateway" is resolved to all current default routing
72           gateway addresses, ordered by their metric. This assigns a stable
73           hostname to the current gateway, useful for referencing it
74           independently of the current network configuration state.
75
76       ·   The mappings defined in /etc/hosts are resolved to their configured
77           addresses and back, but they will not affect lookups for
78           non-address types (like MX).
79
80       Lookup requests are routed to the available DNS servers, LLMNR and
81       MulticastDNS interfaces according to the following rules:
82
83       ·   Lookups for the special hostname "localhost" are never routed to
84           the network. (A few other, special domains are handled the same
85           way.)
86
87       ·   Single-label names are routed to all local interfaces capable of IP
88           multicasting, using the LLMNR protocol. Lookups for IPv4 addresses
89           are only sent via LLMNR on IPv4, and lookups for IPv6 addresses are
90           only sent via LLMNR on IPv6. Lookups for the locally configured
91           host name and the "_gateway" host name are never routed to LLMNR.
92
93       ·   Multi-label names with the domain suffix ".local" are routed to all
94           local interfaces capable of IP multicasting, using the MulticastDNS
95           protocol. As with LLMNR IPv4 address lookups are sent via IPv4 and
96           IPv6 address lookups are sent via IPv6.
97
98       ·   Other multi-label names are routed to all local interfaces that
99           have a DNS server configured, plus the globally configured DNS
100           server if there is one. Address lookups from the link-local address
101           range are never routed to DNS. Note that by default lookups for
102           domains with the ".local" suffix are not routed to DNS servers,
103           unless the domain is specified explicitly as routing or search
104           domain for the DNS server and interface. This means that on
105           networks where the ".local" domain is defined in a site-specific
106           DNS server, explicit search or routing domains need to be
107           configured to make lookups within this DNS domain work. Note that
108           today it's generally recommended to avoid defining ".local" in a
109           DNS server, as RFC6762[3] reserves this domain for exclusive
110           MulticastDNS use.
111
112       If lookups are routed to multiple interfaces, the first successful
113       response is returned (thus effectively merging the lookup zones on all
114       matching interfaces). If the lookup failed on all interfaces, the last
115       failing response is returned.
116
117       Routing of lookups may be influenced by configuring per-interface
118       domain names. See systemd.network(5) for details. Lookups for a
119       hostname ending in one of the per-interface domains are exclusively
120       routed to the matching interfaces.
121
122       See the resolved D-Bus API Documentation[1] for information about the
123       APIs systemd-resolved provides.
124

/ETC/RESOLV.CONF

126       Four modes of handling /etc/resolv.conf (see resolv.conf(5)) are
127       supported:
128
129       ·   systemd-resolved maintains the
130           /run/systemd/resolve/stub-resolv.conf file for compatibility with
131           traditional Linux programs. This file may be symlinked from
132           /etc/resolv.conf. This file lists the 127.0.0.53 DNS stub (see
133           above) as the only DNS server. It also contains a list of search
134           domains that are in use by systemd-resolved. The list of search
135           domains is always kept up-to-date. Note that
136           /run/systemd/resolve/stub-resolv.conf should not be used directly
137           by applications, but only through a symlink from /etc/resolv.conf.
138           This file may be symlinked from /etc/resolv.conf in order to
139           connect all local clients that bypass local DNS APIs to
140           systemd-resolved with correct search domains settings. This mode of
141           operation is recommended.
142
143       ·   A static file /usr/lib/systemd/resolv.conf is provided that lists
144           the 127.0.0.53 DNS stub (see above) as only DNS server. This file
145           may be symlinked from /etc/resolv.conf in order to connect all
146           local clients that bypass local DNS APIs to systemd-resolved. This
147           file does not contain any search domains.
148
149       ·   systemd-resolved maintains the /run/systemd/resolve/resolv.conf
150           file for compatibility with traditional Linux programs. This file
151           may be symlinked from /etc/resolv.conf and is always kept
152           up-to-date, containing information about all known DNS servers.
153           Note the file format's limitations: it does not know a concept of
154           per-interface DNS servers and hence only contains system-wide DNS
155           server definitions. Note that /run/systemd/resolve/resolv.conf
156           should not be used directly by applications, but only through a
157           symlink from /etc/resolv.conf. If this mode of operation is used
158           local clients that bypass any local DNS API will also bypass
159           systemd-resolved and will talk directly to the known DNS servers.
160
161       ·   Alternatively, /etc/resolv.conf may be managed by other packages,
162           in which case systemd-resolved will read it for DNS configuration
163           data. In this mode of operation systemd-resolved is consumer rather
164           than provider of this configuration file.
165
166       Note that the selected mode of operation for this file is detected
167       fully automatically, depending on whether /etc/resolv.conf is a symlink
168       to /run/systemd/resolve/resolv.conf or lists 127.0.0.53 as DNS server.
169

SIGNALS

171       SIGUSR1
172           Upon reception of the SIGUSR1 process signal systemd-resolved will
173           dump the contents of all DNS resource record caches it maintains,
174           as well as all feature level information it learnt about configured
175           DNS servers into the system logs.
176
177       SIGUSR2
178           Upon reception of the SIGUSR2 process signal systemd-resolved will
179           flush all caches it maintains. Note that it should normally not be
180           necessary to request this explicitly – except for debugging
181           purposes – as systemd-resolved flushes the caches automatically
182           anyway any time the host's network configuration changes. Sending
183           this signal to systemd-resolved is equivalent to the resolvectl
184           --flush-caches command, however the latter is recommended since it
185           operates in a synchronous way.
186
187       SIGRTMIN+1
188           Upon reception of the SIGRTMIN+1 process signal systemd-resolved
189           will forget everything it learnt about the configured DNS servers.
190           Specifically any information about server feature support is
191           flushed out, and the server feature probing logic is restarted on
192           the next request, starting with the most fully featured level. Note
193           that it should normally not be necessary to request this explicitly
194           – except for debugging purposes – as systemd-resolved automatically
195           forgets learnt information any time the DNS server configuration
196           changes. Sending this signal to systemd-resolved is equivalent to
197           the resolvectl --reset-server-features command, however the latter
198           is recommended since it operates in a synchronous way.
199

SEE ALSO

201       systemd(1), resolved.conf(5), dnssec-trust-anchors.d(5), nss-
202       resolve(8), resolvectl(1), resolv.conf(5), hosts(5),
203       systemd.network(5), systemd-networkd.service(8)
204

NOTES

206        1. API Documentation
207           https://www.freedesktop.org/wiki/Software/systemd/resolved
208
209        2. RFC3493
210           https://tools.ietf.org/html/rfc3493
211
212        3. RFC6762
213           https://tools.ietf.org/html/rfc6762
214
215
216
217systemd 239                                        SYSTEMD-RESOLVED.SERVICE(8)
Impressum