resolvectl

Query and control DNS resolver

TLDR

Show DNS settings

$ resolvectl status

Resolve the IPv4 and IPv6 addresses for one or more domains

$ resolvectl query [domain1 domain2 ...]

Retrieve the domain of a specified IP address

$ resolvectl query [ip_address]

Flush all local DNS caches

$ resolvectl flush-caches

Display DNS statistics (transactions, cache, and DNSSEC verdicts)

$ resolvectl statistics

Retrieve an MX record of a domain

$ resolvectl --legend [no] [[-t|--type]] [MX] query [domain]

Resolve an SRV record, for example _xmpp-server._tcp gmail.com

$ resolvectl service _[service]._[protocol] [name]

Retrieve a TLS key

$ resolvectl tlsa tcp [domain]:443

SYNOPSIS

resolvectl [OPTIONS...] COMMAND [NAME...]

status
    Show the current DNS server and link settings configured for systemd-resolved.

query ...
    Resolve one or more network names, IP addresses, or DNS resource records.

flush-caches
    Flush the local DNS resource record cache managed by systemd-resolved.

statistics
    Show current cache statistics, including cache entries, hits, and misses.

dns ...
    Set the DNS servers to use for the specified network interface.

domain ...
    Set the DNS search domains to use for the specified network interface.

llmnr
    Control LLMNR (Link-Local Multicast Name Resolution) for an interface. Modes: yes, no, resolve, dont-resolve.

mdns
    Control mDNS (Multicast DNS) for an interface. Modes: yes, no, resolve, dont-resolve.

log-level
    Get or set the current log level for systemd-resolved.service.

revert
    Revert the DNS settings for the specified interface to their defaults.

--json=pretty|short|off
    Output in JSON format. 'pretty' for formatted, 'short' for condensed, 'off' (default) for plain.

-h, --help
    Show a short help text and exit.

--version
    Show a short version string and exit.

DESCRIPTION

resolvectl is a command-line client for systemd-resolved.service, a system service that provides network name resolution for local applications. It offers a standardized API for DNS, LLMNR (Link-Local Multicast Name Resolution), and mDNS (Multicast DNS) queries. resolvectl allows administrators to query, configure, and inspect the state of the systemd-resolved DNS stub resolver. It can be used to show current DNS servers configured, inspect DNS cache statistics, flush the local DNS cache, resolve specific hostnames or IP addresses, and manage per-interface DNS settings, including servers, search domains, and LLMNR/mDNS modes. This tool simplifies DNS management on systemd-based Linux systems by centralizing resolution services.

CAVEATS

resolvectl requires the systemd-resolved.service to be running and active. Configuration changes made via resolvectl are often temporary and might be overridden by network management tools (like NetworkManager or systemd-networkd) if not integrated properly. It is primarily designed for use on systemd-based Linux distributions.

DNS CACHING

resolvectl interacts with systemd-resolved's built-in DNS cache. This cache stores resolved DNS queries to speed up subsequent lookups for the same domains, reducing network traffic and improving application responsiveness. The flush-caches and statistics commands provide direct control and insight into this caching mechanism.

SERVICE DISCOVERY PROTOCOLS

Beyond traditional DNS, resolvectl supports LLMNR (Link-Local Multicast Name Resolution) and mDNS (Multicast DNS). These protocols enable hostname resolution and service discovery on local networks without requiring a central DNS server. This is particularly useful for ad-hoc networks or discovering devices like printers and media servers.

INTEGRATION WITH NSS

systemd-resolved integrates with the GNU C Library's Name Service Switch (NSS) through the nss-resolve module. This allows standard system APIs like gethostbyname() to query systemd-resolved for hostnames, ensuring that all applications on the system can benefit from its resolution services, caching, and protocol support.

HISTORY

resolvectl is an integral part of the systemd project, which began development in 2010. It was introduced as a client for systemd-resolved.service, which emerged as systemd's answer to centralized and modern network name resolution. Prior to its widespread adoption, DNS configuration was typically managed through static files like /etc/resolv.conf. resolvectl and systemd-resolved aim to provide a more dynamic, robust, and unified approach, handling DNS, LLMNR, and mDNS, along with local caching, to improve resolution performance and reliability on contemporary Linux systems.