1 <?xml version='
1.0'
?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2014 Tom Gundersen
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
26 <refentry id=
"systemd-resolved.service" conditional='ENABLE_RESOLVE'
>
29 <title>systemd-resolved.service
</title>
30 <productname>systemd
</productname>
34 <contrib>Developer
</contrib>
35 <firstname>Tom
</firstname>
36 <surname>Gundersen
</surname>
37 <email>teg@jklm.no
</email>
43 <refentrytitle>systemd-resolved.service
</refentrytitle>
44 <manvolnum>8</manvolnum>
48 <refname>systemd-resolved.service
</refname>
49 <refname>systemd-resolved
</refname>
50 <refpurpose>Network Name Resolution manager
</refpurpose>
54 <para><filename>systemd-resolved.service
</filename></para>
55 <para><filename>/usr/lib/systemd/systemd-resolved
</filename></para>
59 <title>Description
</title>
61 <para><command>systemd-resolved
</command> is a system service that provides network name resolution to local
62 applications. It implements a caching and validating DNS/DNSSEC stub resolver, as well as an LLMNR resolver and
63 responder. Local applications may submit network name resolution requests via three interfaces:
</para>
66 <listitem><para>The native, fully-featured API
<command>systemd-resolved
</command> exposes on the bus. See the
67 <ulink url=
"https://www.freedesktop.org/wiki/Software/systemd/resolved">API Documentation
</ulink> for
68 details. Usage of this API is generally recommended to clients as it is asynchronous and fully featured (for
69 example, properly returns DNSSEC validation status and interface scope for addresses as necessary for supporting
70 link-local networking).
</para></listitem>
72 <listitem><para>The glibc
73 <citerefentry project='man-pages'
><refentrytitle>getaddrinfo
</refentrytitle><manvolnum>3</manvolnum></citerefentry> API as defined
74 by
<ulink url=
"https://tools.ietf.org/html/rfc3493">RFC3493
</ulink> and its related resolver functions,
75 including
<citerefentry project='man-pages'
><refentrytitle>gethostbyname
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
76 API is widely supported, including beyond the Linux platform. In its current form it does not expose DNSSEC
77 validation status information however, and is synchronous only. This API is backed by the glibc Name Service
78 Switch (
<citerefentry project='man-pages'
><refentrytitle>nss
</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Usage of the
79 glibc NSS module
<citerefentry><refentrytitle>nss-resolve
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
80 is required in order to allow glibc's NSS resolver functions to resolve host names via
81 <command>systemd-resolved
</command>.
</para></listitem>
83 <listitem><para>Additionally,
<command>systemd-resolved
</command> provides a local DNS stub listener on IP
84 address
127.0.0.53 on the local loopback interface. Programs issuing DNS requests directly, bypassing any local
85 API may be directed to this stub, in order to connect them to
<command>systemd-resolved
</command>. Note however
86 that it is strongly recommended that local programs use the glibc NSS or bus APIs instead (as described above),
87 as various network resolution concepts (such as link-local addressing, or LLMNR Unicode domains) cannot be mapped
88 to the unicast DNS protocol.
</para></listitem>
91 <para>The DNS servers contacted are determined from the global settings in
92 <filename>/etc/systemd/resolved.conf
</filename>, the per-link static settings in
93 <filename>/etc/systemd/network/*.network
</filename> files, the per-link dynamic settings received over DHCP and any
94 DNS server information made available by other system services. See
95 <citerefentry><refentrytitle>resolved.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
96 <citerefentry><refentrytitle>systemd.network
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details
97 about systemd's own configuration files for DNS servers. To improve compatibility,
98 <filename>/etc/resolv.conf
</filename> is read in order to discover configured system DNS servers, but only if it is
99 not a symlink to
<filename>/run/systemd/resolve/stub-resolv.conf
</filename> or
100 <filename>/run/systemd/resolve/resolv.conf
</filename> (see below).
</para>
102 <para><command>systemd-resolved
</command> synthesizes DNS resource records (RRs) for the following cases:
</para>
105 <listitem><para>The local, configured hostname is resolved to
106 all locally configured IP addresses ordered by their scope, or
107 — if none are configured — the IPv4 address
127.0.0.2 (which
108 is on the local loopback) and the IPv6 address ::
1 (which is the
109 local host).
</para></listitem>
111 <listitem><para>The hostnames
<literal>localhost
</literal> and
112 <literal>localhost.localdomain
</literal> (as well as any hostname
113 ending in
<literal>.localhost
</literal> or
<literal>.localhost.localdomain
</literal>)
114 are resolved to the IP addresses
127.0.0.1 and ::
1.
</para></listitem>
116 <listitem><para>The hostname
<literal>_gateway
</literal> is
117 resolved to all current default routing gateway addresses,
118 ordered by their metric. This assigns a stable hostname to the
119 current gateway, useful for referencing it independently of the
120 current network configuration state.
</para></listitem>
122 <listitem><para>The mappings defined in
<filename>/etc/hosts
</filename> are resolved
123 to their configured addresses and back, but they will not affect lookups for
124 non-address types (like MX).
</para></listitem>
127 <para>Lookup requests are routed to the available DNS servers
128 and LLMNR interfaces according to the following rules:
</para>
131 <listitem><para>Lookups for the special hostname
132 <literal>localhost
</literal> are never routed to the
133 network. (A few other, special domains are handled the same way.)
</para></listitem>
135 <listitem><para>Single-label names are routed to all local
136 interfaces capable of IP multicasting, using the LLMNR
137 protocol. Lookups for IPv4 addresses are only sent via LLMNR on
138 IPv4, and lookups for IPv6 addresses are only sent via LLMNR on
139 IPv6. Lookups for the locally configured host name and the
140 <literal>_gateway
</literal> host name are never routed to
141 LLMNR.
</para></listitem>
143 <listitem><para>Multi-label names are routed to all local
144 interfaces that have a DNS server configured, plus the globally
145 configured DNS server if there is one. Address lookups from the
146 link-local address range are never routed to
147 DNS.
</para></listitem>
150 <para>If lookups are routed to multiple interfaces, the first
151 successful response is returned (thus effectively merging the
152 lookup zones on all matching interfaces). If the lookup failed on
153 all interfaces, the last failing response is returned.
</para>
155 <para>Routing of lookups may be influenced by configuring
156 per-interface domain names. See
157 <citerefentry><refentrytitle>systemd.network
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
158 for details. Lookups for a hostname ending in one of the
159 per-interface domains are exclusively routed to the matching
162 <para>See the
<ulink url=
"https://www.freedesktop.org/wiki/Software/systemd/resolved"> resolved D-Bus API
163 Documentation
</ulink> for information about the APIs
<filename>systemd-resolved
</filename> provides.
</para>
168 <title><filename>/etc/resolv.conf
</filename></title>
170 <para>Four modes of handling
<filename>/etc/resolv.conf
</filename> (see
171 <citerefentry project='man-pages'
><refentrytitle>resolv.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>) are
175 <listitem><para><command>systemd-resolved
</command> maintains the
176 <filename>/run/systemd/resolve/stub-resolv.conf
</filename> file for compatibility with traditional Linux
177 programs. This file may be symlinked from
<filename>/etc/resolv.conf
</filename>. This file lists the
127.0.0.53
178 DNS stub (see above) as the only DNS server. It also contains a list of search domains that are in use by
179 systemd-resolved. The list of search domains is always kept up-to-date. Note that
180 <filename>/run/systemd/resolve/stub-resolv.conf
</filename> should not be used directly by applications, but only
181 through a symlink from
<filename>/etc/resolv.conf
</filename>. This file may be symlinked from
182 <filename>/etc/resolv.conf
</filename> in order to connect all local clients that bypass local DNS APIs to
183 <command>systemd-resolved
</command> with correct search domains settings. This mode of operation is
184 recommended.
</para></listitem>
186 <listitem><para>A static file
<filename>/usr/lib/systemd/resolv.conf
</filename> is provided that lists
187 the
127.0.0.53 DNS stub (see above) as only DNS server. This file may be symlinked from
188 <filename>/etc/resolv.conf
</filename> in order to connect all local clients that bypass local DNS APIs to
189 <command>systemd-resolved
</command>. This file does not contain any search domains.
</para></listitem>
191 <listitem><para><command>systemd-resolved
</command> maintains the
192 <filename>/run/systemd/resolve/resolv.conf
</filename> file for compatibility with traditional Linux
193 programs. This file may be symlinked from
<filename>/etc/resolv.conf
</filename> and is always kept up-to-date,
194 containing information about all known DNS servers. Note the file format's limitations: it does not know a
195 concept of per-interface DNS servers and hence only contains system-wide DNS server definitions. Note that
196 <filename>/run/systemd/resolve/resolv.conf
</filename> should not be used directly by applications, but only
197 through a symlink from
<filename>/etc/resolv.conf
</filename>. If this mode of operation is used local clients
198 that bypass any local DNS API will also bypass
<command>systemd-resolved
</command> and will talk directly to the
199 known DNS servers.
</para> </listitem>
201 <listitem><para>Alternatively,
<filename>/etc/resolv.conf
</filename> may be managed by other packages, in which
202 case
<command>systemd-resolved
</command> will read it for DNS configuration data. In this mode of operation
203 <command>systemd-resolved
</command> is consumer rather than provider of this configuration
204 file.
</para></listitem>
207 <para>Note that the selected mode of operation for this file is detected fully automatically, depending on whether
208 <filename>/etc/resolv.conf
</filename> is a symlink to
<filename>/run/systemd/resolve/resolv.conf
</filename> or
209 lists
127.0.0.53 as DNS server.
</para>
213 <title>Signals
</title>
217 <term><constant>SIGUSR1
</constant></term>
219 <listitem><para>Upon reception of the
<constant>SIGUSR1
</constant> process signal
220 <command>systemd-resolved
</command> will dump the contents of all DNS resource record caches it maintains, as
221 well as all feature level information it learnt about configured DNS servers into the system
222 logs.
</para></listitem>
226 <term><constant>SIGUSR2
</constant></term>
228 <listitem><para>Upon reception of the
<constant>SIGUSR2
</constant> process signal
229 <command>systemd-resolved
</command> will flush all caches it maintains. Note that it should normally not be
230 necessary to request this explicitly – except for debugging purposes – as
<command>systemd-resolved
</command>
231 flushes the caches automatically anyway any time the host's network configuration changes. Sending this signal
232 to
<command>systemd-resolved
</command> is equivalent to the
<command>systemd-resolve --flush-caches
</command>
233 command, however the latter is recommended since it operates in a synchronous way.
</para></listitem>
237 <term><constant>SIGRTMIN+
1</constant></term>
239 <listitem><para>Upon reception of the
<constant>SIGRTMIN+
1</constant> process signal
240 <command>systemd-resolved
</command> will forget everything it learnt about the configured DNS
241 servers. Specifically any information about server feature support is flushed out, and the server feature
242 probing logic is restarted on the next request, starting with the most fully featured level. Note that it
243 should normally not be necessary to request this explicitly – except for debugging purposes – as
244 <command>systemd-resolved
</command> automatically forgets learnt information any time the DNS server
245 configuration changes. Sending this signal to
<command>systemd-resolved
</command> is equivalent to the
246 <command>systemd-resolve --reset-server-features
</command> command, however the latter is recommended since it
247 operates in a synchronous way.
</para></listitem>
254 <title>See Also
</title>
256 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
257 <citerefentry><refentrytitle>resolved.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
258 <citerefentry><refentrytitle>dnssec-trust-anchors.d
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
259 <citerefentry><refentrytitle>nss-resolve
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
260 <citerefentry><refentrytitle>systemd-resolve
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
261 <citerefentry project='man-pages'
><refentrytitle>resolv.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
262 <citerefentry project='man-pages'
><refentrytitle>hosts
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
263 <citerefentry><refentrytitle>systemd.network
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
264 <citerefentry><refentrytitle>systemd-networkd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>