systemd-resolved.service - Man Page

Network Name Resolution manager

Synopsis

systemd-resolved.service

/usr/lib/systemd/systemd-resolved

Description

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 and MulticastDNS resolver and responder. Local applications may submit network name resolution requests via three interfaces:

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 (in case systemd-networkd.service(8) is used), the per-link dynamic settings received over DHCP, information provided via resolvectl(1), and any DNS server information made available by other system services. See resolved.conf(5) and systemd.network(5) 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/stub-resolv.conf, /usr/lib/systemd/resolv.conf or /run/systemd/resolve/resolv.conf (see below).

Synthetic Records

systemd-resolved synthesizes DNS resource records (RRs) for the following cases:

Protocols and Routing

The lookup requests that systemd-resolved.service receives are routed to the available DNS servers, LLMNR, and MulticastDNS interfaces according to the following rules:

If lookups are routed to multiple interfaces, the first successful response is returned (thus effectively merging the lookup zones on all matching interfaces). If the lookup failed on all interfaces, the last failing response is returned.

Routing of lookups is determined by the per-interface routing domains (search and route-only) and global search domains. See systemd.network(5) and resolvectl(1) for a description how those settings are set dynamically and the discussion of Domains= in resolved.conf(5) for a description of globally configured DNS settings.

The following query routing logic applies for unicast DNS lookups initiated by systemd-resolved.service:

The DefaultRoute= option is a boolean setting configurable with resolvectl or in .network files. If not set, it is implicitly determined based on the configured DNS domains for a link: if there's a route-only domain other than "~.", it defaults to false, otherwise to true.

Effectively this means: in order to support single-label non-synthesized names, define appropriate search domains. In order to preferably route all DNS queries not explicitly matched by routing domain configuration to a specific link, configure a "~." route-only domain on it. This will ensure that other links will not be considered for these queries (unless they too carry such a routing domain). In order to route all such DNS queries to a specific link only if no other link is preferred, set the DefaultRoute= option for the link to true and do not configure a "~." route-only domain on it. Finally, in order to ensure that a specific link never receives any DNS traffic not matching any of its configured routing domains, set the DefaultRoute= option for it to false.

See org.freedesktop.resolve1(5) for information about the D-Bus APIs systemd-resolved provides.

Compatibility with the Traditional Glibc Stub Resolver

This section provides a short summary of differences in the resolver implemented by nss-resolve(8) together with systemd-resolved and the traditional stub resolver implemented in nss-dns.

/etc/resolv.conf

Four modes of handling /etc/resolv.conf (see resolv.conf(5)) are supported:

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

SIGUSR1

Upon reception of the SIGUSR1 process signal systemd-resolved will dump the contents of all DNS resource record caches it maintains, as well as all feature level information it learnt about configured DNS servers into the system logs.

Added in version 231.

SIGUSR2

Upon reception of the SIGUSR2 process signal systemd-resolved will flush all caches it maintains. Note that it should normally not be necessary to request this explicitly – except for debugging purposes – as systemd-resolved flushes the caches automatically anyway any time the host's network configuration changes. Sending this signal to systemd-resolved is equivalent to the resolvectl flush-caches command, however the latter is recommended since it operates in a synchronous way.

Added in version 231.

SIGRTMIN+1

Upon reception of the SIGRTMIN+1 process signal systemd-resolved will forget everything it learnt about the configured DNS servers. Specifically any information about server feature support is flushed out, and the server feature probing logic is restarted on the next request, starting with the most fully featured level. Note that it should normally not be necessary to request this explicitly – except for debugging purposes – as systemd-resolved automatically forgets learnt information any time the DNS server configuration changes. Sending this signal to systemd-resolved is equivalent to the resolvectl reset-server-features command, however the latter is recommended since it operates in a synchronous way.

Added in version 235.

Credentials

systemd-resolved supports the service credentials logic as implemented by ImportCredential=/LoadCredential=/SetCredential= (see systemd.exec(5) for details). The following credentials are used when passed in:

network.dns,  network.search_domains

May contain a space separated list of DNS server IP addresses and DNS search domains. This information is only used when no explicit configuration via /etc/systemd/resolved.conf, /etc/resolv.conf or the kernel command line has been provided.

Added in version 253.

Kernel Command Line

systemd-resolved also honours two kernel command line options:

nameserver=, domain=

Takes the IP address of a DNS server (in case of nameserver=), and a DNS search domain (in case of domain=). May be used multiple times, to define multiple DNS servers/search domains. If either of these options are specified /etc/resolv.conf will not be read and the DNS= and Domains= settings of resolved.conf(5) will be ignored. These two kernel command line options hence override system configuration.

Added in version 253.

IP Ports

The systemd-resolved service listens on the following IP ports:

See Also

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

Notes

  1. RFC3493
    https://tools.ietf.org/html/rfc3493
  2. RFC6762
    https://tools.ietf.org/html/rfc6762
  3. For example, if /etc/resolv.conf has

    nameserver 127.0.0.53
    search foobar.com barbar.com

    and we look up "localhost", nss-dns will send the following queries to systemd-resolved listening on 127.0.0.53:53: first "localhost.foobar.com", then "localhost.barbar.com", and finally "localhost". If (hopefully) the first two queries fail, systemd-resolved will synthesize an answer for the third query.

    When using nss-dns with any search domains, it is thus crucial to always configure nss-files with higher priority and provide mappings for names that should not be resolved using search domains.

  4. There are currently more than 1500 top-level domain names defined, and new ones are added regularly, often using "attractive" names that are also likely to be used locally. Not looking up multi-label names in this fashion avoids fragility in both directions: a valid global name could be obscured by a local name, and resolution of a relative local name could suddenly break when a new top-level domain is created, or when a new subdomain of a top-level domain in registered. Resolving any given name as either relative or absolute avoids this ambiguity.

Referenced By

dnssec-trust-anchors.d(5), kernel-command-line(7), nss-resolve(8), org.freedesktop.resolve1(5), resolvectl(1), resolved.conf(5), slirp4netns(1), systemd.directives(7), systemd.dnssd(5), systemd.index(7), systemd.network(5), systemd-nspawn(1), systemd.system-credentials(7), varlinkctl(1).

The man page systemd-resolved(8) is an alias of systemd-resolved.service(8).

systemd 255