1SYSTEMD-RESOLVED.SERVICE(8)systemd-resolved.serviceSYSTEMD-RESOLVED.SERVICE(8)
2
6 systemd-resolved.service, systemd-resolved - Network Name Resolution
7 manager
8
10 systemd-resolved.service
11 /usr/lib/systemd/systemd-resolved
13
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 · 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 · 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 · 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 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 systemd-resolved synthesizes DNS resource records (RRs) for the
60 following cases:
61 · 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 · 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 · 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 · 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 Lookup requests are routed to the available DNS servers, LLMNR and
81 MulticastDNS interfaces according to the following rules:
82 · 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 · 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 · 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 · 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 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 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 See the resolved D-Bus API Documentation[1] for information about the
123 APIs systemd-resolved provides.
124
126 Four modes of handling /etc/resolv.conf (see resolv.conf(5)) are
127 supported:
128 · 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 · 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 · 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 · 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 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
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 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 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
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
206 1. API Documentation
207 https://www.freedesktop.org/wiki/Software/systemd/resolved
208 2. RFC3493
210 https://tools.ietf.org/html/rfc3493
211 3. RFC6762
213 https://tools.ietf.org/html/rfc6762
214systemd 239 SYSTEMD-RESOLVED.SERVICE(8)