man/systemd-resolved.service.xml

   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">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2014 Tom Gundersen
  11
  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.
  16
  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.
  21
  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/>.
  24 -->
  25
  26 <refentry id="systemd-resolved.service" conditional='ENABLE_RESOLVE'>
  27
  28   <refentryinfo>
  29     <title>systemd-resolved.service</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Tom</firstname>
  36         <surname>Gundersen</surname>
  37         <email>teg@jklm.no</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>systemd-resolved.service</refentrytitle>
  44     <manvolnum>8</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>systemd-resolved.service</refname>
  49     <refname>systemd-resolved</refname>
  50     <refpurpose>Network Name Resolution manager</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv>
  54     <para><filename>systemd-resolved.service</filename></para>
  55     <para><filename>/usr/lib/systemd/systemd-resolved</filename></para>
  56   </refsynopsisdiv>
  57
  58   <refsect1>
  59     <title>Description</title>
  60
  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>
  64
  65     <itemizedlist>
  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>
  71
  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>
  82
  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>
  89     </itemizedlist>
  90
  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>
 101
 102     <para><command>systemd-resolved</command> synthesizes DNS resource records (RRs) for the following cases:</para>
 103
 104     <itemizedlist>
 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>
 110
 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>
 115
 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>
 121
 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>
 125     </itemizedlist>
 126
 127     <para>Lookup requests are routed to the available DNS servers
 128     and LLMNR interfaces according to the following rules:</para>
 129
 130     <itemizedlist>
 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>
 134
 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>
 142
 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>
 148     </itemizedlist>
 149
 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>
 154
 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
 160     interfaces.</para>
 161
 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>
 164
 165   </refsect1>
 166
 167   <refsect1>
 168     <title><filename>/etc/resolv.conf</filename></title>
 169
 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
 172     supported:</para>
 173
 174     <itemizedlist>
 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>
 185
 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>
 190
 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>
 200
 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>
 205     </itemizedlist>
 206
 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>
 210   </refsect1>
 211
 212   <refsect1>
 213     <title>Signals</title>
 214
 215     <variablelist>
 216       <varlistentry>
 217         <term><constant>SIGUSR1</constant></term>
 218
 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>
 223       </varlistentry>
 224
 225       <varlistentry>
 226         <term><constant>SIGUSR2</constant></term>
 227
 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>
 234       </varlistentry>
 235
 236       <varlistentry>
 237         <term><constant>SIGRTMIN+1</constant></term>
 238
 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>
 248       </varlistentry>
 249     </variablelist>
 250
 251   </refsect1>
 252
 253   <refsect1>
 254     <title>See Also</title>
 255     <para>
 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>
 265     </para>
 266   </refsect1>
 267
 268 </refentry>