From ArchWiki
(Redirected from Systemd-resolvconf)
Jump to navigation Jump to search

systemd-resolved is a systemd service that provides network name resolution to local applications via a D-Bus interface, the resolve NSS service (nss-resolve(8)), and a local DNS stub listener on See systemd-resolved(8) for the usage.


systemd-resolved is a part of the systemd package that is installed by default.


systemd-resolved provides resolver services for Domain Name System (DNS) (including DNSSEC and DNS over TLS), Multicast DNS (mDNS) and Link-Local Multicast Name Resolution (LLMNR).

The resolver can be configured by editing /etc/systemd/resolved.conf and/or drop-in .conf files in /etc/systemd/resolved.conf.d/. See resolved.conf(5).

To use systemd-resolved start and enable systemd-resolved.service.

Tip: To understand the context around the choices and switches, one can turn on detailed debug information for systemd-resolved as described in systemd#Diagnosing a service.


systemd-resolved has four different modes for handling the Domain name resolution (the four modes are described in systemd-resolved(8) § /ETC/RESOLV.CONF). We will focus here on the two most relevant modes.

  1. Using the systemd DNS stub file - the systemd DNS stub file /run/systemd/resolve/stub-resolv.conf contains the local stub as the only DNS server and a list of search domains. This is the recommended mode of operation. The service users are advised to redirect the /etc/resolv.conf file to the local stub DNS resolver file /run/systemd/resolve/stub-resolv.conf managed by systemd-resolved. This propagates the systemd managed configuration to all the clients. This can be done by replacing /etc/resolv.conf with a symbolic link to the systemd stub:
    # ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
  2. Preserving resolv.conf - this mode preserves /etc/resolv.conf and systemd-resolved is simply a client of this file. This mode is less disruptive as /etc/resolv.conf can continue to be managed by other packages.
  • The mode of operation of systemd-resolved is detected automatically, depending on whether /etc/resolv.conf is a symlink to the local stub DNS resolver file or contains server names.
  • Creating the /etc/resolv.conf symlink will not be possible while inside arch-chroot, since the file is bind-mounted from the outside system. Instead, create the symlink from outside the chroot. E.g. ln -sf /run/systemd/resolve/stub-resolv.conf /mnt/etc/resolv.conf.

Setting DNS servers

Tip: To check the DNS currently in use by systemd-resolved, run resolvectl status.

systemd-resolved will work out of the box with a network manager using /etc/resolv.conf. No particular configuration is required since systemd-resolved will be detected by following the /etc/resolv.conf symlink. This is going to be the case with systemd-networkd or NetworkManager.

However, if the DHCP and VPN clients use the resolvconf program to set name servers and search domains (see openresolv#Users for a list of software that use resolvconf), the additional package systemd-resolvconf is needed to provide the /usr/bin/resolvconf symlink.


In local DNS stub mode, custom DNS server(s) can be set in the resolved.conf(5) file:

DNS= fd7b:d0bd:7a6e::1
  • Without the Domains=~. option in resolved.conf(5), systemd-resolved might use the per-link DNS servers, if any of them set Domains=~. in the per-link configuration.
  • This option will not affect queries of domain names that match the more specific search domains specified in per-link configuration, they will still be resolved using their respective per-link DNS servers.

For more information on per-link configuration see systemd-networkd#network files.


If systemd-resolved does not receive DNS server addresses from the network manager and no DNS servers are configured manually then systemd-resolved falls back to the fallback DNS addresses to ensure that DNS resolution always works.

Note: The fallback DNS are in this order: Cloudflare, Quad9 (without filtering and without DNSSEC) and Google; see the systemd PKGBUILD where the servers are defined.

The addresses can be changed by setting FallbackDNS= in resolved.conf(5). E.g.:

FallbackDNS= ::1

To disable the fallback DNS functionality set the FallbackDNS option without specifying any addresses:



DNSSEC validation can be enabled by changing DNSSEC= setting in resolved.conf(5).

  • Set DNSSEC=allow-downgrade to validate DNSSEC only if the upstream DNS server supports it.
  • Set DNSSEC=true to always validate DNSSEC, thus breaking DNS resolution with name servers that do not support it. For example:
  • If your DNS server does not support DNSSEC and you experience problems with the default allow-downgrade mode (e.g. systemd issue 10579), you can explicitly disable systemd-resolved's DNSSEC support by setting DNSSEC=false.
  • systemd-resolved may disable DNSSEC after a few unsuccessful validations. If the DNSSEC option is set to true, then DNS resolution will stop working entirely. See systemd issue 9867.

Test DNSSEC validation by querying a domain with a invalid signature:

$ resolvectl query resolve call failed: DNSSEC validation failed: invalid

Now test a domain with valid signature:

$ resolvectl query

-- Information acquired via protocol DNS in 266.3ms.
-- Data is authenticated: yes

DNS over TLS

Warning: Prior to systemd version 245.2-2, systemd-resolved only validated the DNS server certificate if it was issued for the server's IP address (a rare occurrence). DNS server certificates without an IP address were not checked making systemd-resolved vulnerable to man-in-the-middle attacks. See systemd issue 9397.

DNS over TLS is disabled by default. To enable it change the DNSOverTLS= setting in the [Resolve] section in resolved.conf(5). To enable validation of your DNS provider's server certificate, include their hostname in the DNS= setting in the format ip_address#hostname. For example:

Note: The DNS server used must support DNS over TLS. Otherwise all DNS requests will fail.

ngrep can be used to test if DNS over TLS is working since DNS over TLS always uses port 853 and never port 53. The command ngrep port 53 should produce no output when a hostname is resolved with DNS over TLS and ngrep port 853 should produce encrypted output.

Wireshark can be used for more detailed packet inspection of DNS over TLS queries. It is provided by the wireshark-cli and wireshark-qt packages.


systemd-resolved is capable of working as a multicast DNS resolver and responder.

The resolver provides hostname resolution using a "hostname.local" naming scheme.

mDNS will only be activated for the connection if both the systemd-resolved's global setting (MulticastDNS= in resolved.conf(5)) and the network manager's per-connection setting is enabled. By default systemd-resolved enables mDNS responder, but both systemd-networkd and NetworkManager[1] do not enable it for connections:

  • For systemd-networkd the setting is MulticastDNS= in the [Network] section. You may also have to set Multicast=yes in the [Link] section. See
  • For NetworkManager the setting is mdns= in the [connection] section. See nm-settings(5). You will also need to enable it on each interface you want mDNS to work: systemd-resolve --set-mdns=yes --interface=name.
Note: If Avahi has been installed, consider disabling or masking avahi-daemon.service and avahi-daemon.socket to prevent conflicts with systemd-resolved.
Tip: The default for all NetworkManager connections can be set by creating a configuration file in /etc/NetworkManager/conf.d/ and setting connection.mdns= in the [connection] section. See NetworkManager.conf(5).

If you plan to use mDNS and use a firewall, make sure to open UDP port 5353.


Link-Local Multicast Name Resolution is a hostname resolution protocol created by Microsoft.

LLMNR will only be activated for the connection if both the systemd-resolved's global setting (LLMNR= in resolved.conf(5)) and the network manager's per-connection setting is enabled. By default systemd-resolved enables LLMNR responder; systemd-networkd and NetworkManager[2] enable it for connections.

Tip: The default for all NetworkManager connections can be set by creating a configuration file in /etc/NetworkManager/conf.d/ and setting connection.llmnr= in the [connection] section. See NetworkManager.conf(5).

If you plan to use LLMNR and use a firewall, make sure to open UDP and TCP ports 5355.


To query DNS records, mDNS or LLMNR hosts you can use the resolvectl utility.

For example, to query a DNS record:

$ resolvectl query 2a01:4f8:172:1d86::1

-- Information acquired via protocol DNS in 48.4ms.
-- Data is authenticated: no


systemd-resolved not searching the local domain

systemd-resolved may not search the local domain when given just the hostname, even when UseDomains=yes or Domains=[domain-list] is present in the appropriate systemd-networkd's .network file, and that file produces the expected search [domain-list] in resolv.conf. You can run networkctl status or resolvectl status to check if the search domains are actually being picked up.

Possible workarounds:

  • Disable LLMNR to let systemd-resolved immediately continue with appending the DNS suffixes
  • Trim /etc/nsswitch.conf's hosts database (e.g., by removing [!UNAVAIL=return] option after resolve service)
  • Switch to using fully-qualified domain names
  • Use /etc/hosts to resolve hostnames
  • Fall back to using glibc's dns instead of using systemd's resolve

systemd-resolved does not resolve hostnames without suffix

To make systemd-resolved resolve hostnames that are not fully qualified domain names, add ResolveUnicastSingleLabel=yes to /etc/systemd/resolved.conf.

Warning: This will forward single-label names to global DNS servers which may not be under your control. This behaviour is not standard-conformant and may create a privacy and security risk. See resolved.conf(5) for details.

This only seems to work with LLMR disabled (LLMR=no).

If you are using systemd-networkd, you might want the domain supplied by the DHCP server or IPv6 Router Advertisement to be used as a search domain. This is disabled by default, to enable it add to the interface's .network file:



You can check what systemd-resolved has for each interface with:

$ resolvectl domain

See also