RESOLVECTL(1)

📦

version 262.1 · 16 versions

💖 RESOLVECTL(1) 💖

okay bestie, welcome to resolvectl — and yeah, also resolvconf if that's what you typed, they're the same girl 💅

✨ NAME ✨

resolvectl, resolvconf — the way you resolve domain names, IPv4 and IPv6 addresses, DNS resource records, and services, and also peek inside + reconfigure the DNS resolver. it's giving main character energy for your whole DNS situation 🦋

🌸 SYNOPSIS 🌸

resolvectl [OPTIONS...] {COMMAND} [NAME...]

🎀 DESCRIPTION 🎀

so resolvectl is literally your bestie for resolving domain names, IPv4 and IPv6 addresses, DNS resource records and services, all through the systemd-resolved.service(8) resolver service. no cap. 🔥

by default, the list of parameters you hand it gets resolved as hostnames, and it comes back with their IPv4 and IPv6 addresses. but — plot twist — if the parameters you gave are formatted as IPv4 or IPv6 addresses, it does the reverse operation instead, and hands you a hostname for those addresses. it's giving reverse uno card 🙈

the program's output contains info about which protocol was used for the look-up and on which network interface the data was discovered. it also tells you whether the info could be authenticated. all data for which local DNSSEC validation succeeds is considered authenticated. and on top of that, all data originating from local, trusted sources is also reported as authenticated, including resolution of the local host name, the "localhost" hostname, or all data from /etc/hosts. slay 💖

👑 COMMANDS 👑

🔍 `query HOSTNAME|ADDRESS...`

Resolve domain names, as well as IPv4 and IPv6 addresses. when you pair it with --type= or --class= (they're down below 👇), it resolves low-level DNS resource records.

if a single-label domain name is specified it is searched for according to the configured search domains — unless --search=no or --type=/--class= are specified, both of which turn this logic off. so like, pick a lane bestie.

if an international domain name is specified, it is automatically translated according to IDNA rules when resolved via classic DNS — but not for look-ups via MulticastDNS or LLMNR. if --type=/--class= is used, IDNA translation is turned off and domain names are processed as specified. periodt.

if combined with --json= (only supported in combination with --type=) it will output the resource record data in a JSON object. ✨

if systemd-resolved returns a resolution error while --json= is enabled, the error is output as a JSON object. it contains the queried name, the resolved varlink error, and any error fields supplied by systemd-resolved, such as rcode, queryString, extendedDNSErrorCode, extendedDNSErrorMessage, and result. local invocation or connection errors are still reported as regular errors, tho.

Added in version 239.

🌈 `service [[NAME] TYPE] DOMAIN`

Resolve RFC 6763 DNS-SD[1] and RFC 2782 SRV[2] services, depending on the list of parameters you pass. here's the breakdown, bestie:

three parameters? the first is assumed to be the DNS-SD service name, the second the SRV service type, and the third the domain to search in. in this case, a full DNS-SD style SRV and TXT lookup is executed. full send. 🚀
only two parameters? the first is assumed to be the SRV service type, and the second the domain to look in. in this case, no TXT resource record is requested.
only one parameter? it is assumed to be a domain name that is already prefixed with an SRV type, and an SRV lookup is done (no TXT).

Added in version 239.

🔐 `openpgp EMAIL@DOMAIN...`

Query PGP keys stored as OPENPGPKEY resource records, see RFC 7929[3]. the e-mail addresses you specify are converted to the corresponding DNS domain name, and any OPENPGPKEY keys are printed. iconic behavior honestly 💅

the resource record type is implied by this command. if --type= is specified, it must be OPENPGPKEY. no substitutions, bestie.

if combined with --json=, it outputs the resource record data in JSON format. Unauthenticated key data is refused in JSON format. 🚫

Added in version 239.

🧚 `tlsa [FAMILY] DOMAIN[:PORT]...`

Query TLS public keys stored as TLSA resource records, see RFC 6698[4]. a query will be performed for each of the specified names prefixed with the port and family ("_port._family.domain"). the port number may be specified after a colon (":"), otherwise 443 will be used by default. the family may be specified as the first argument, otherwise tcp will be used. defaults are cute like that 🌸

the resource record type is implied by this command. if --type= is specified, it must be TLSA.

if combined with --json=, it outputs the resource record data in JSON format. Unauthenticated key data is refused in JSON format.

Added in version 239.

📊 `status [LINK...]`

Shows the global and per-link DNS settings currently in effect. if no command is specified, this is the implied default. so if you just run resolvectl with nothing else, this is what you get, bestie.

Added in version 239.

📈 `statistics`

Shows general resolver statistics, including info on whether DNSSEC is enabled and available, plus resolution and validation statistics. numbers go brrr 📊✨

Added in version 239.

🔄 `reset-statistics`

Resets the statistics counters shown in statistics to zero. this operation requires root privileges — so no, your regular user self cannot do this one, sorry bestie 😭

Added in version 239.

🧹 `flush-caches`

Flushes all DNS resource record caches the service maintains locally. this is mostly equivalent to sending the SIGUSR2 to the systemd-resolved service. out with the old 🗑️✨

Added in version 239.

🔁 `reset-server-features`

Flushes all feature level info the resolver learnt about specific servers, and ensures that the server feature probing logic is started from the beginning with the next look-up request. this is mostly equivalent to sending the SIGRTMIN+1 to the systemd-resolved service. memory wipe but make it DNS 🧠💫

Added in version 239.

⚙️ `dns [LINK [SERVER...]]`, `domain [LINK [DOMAIN...]]`, `default-route [LINK [BOOL...]]`, `llmnr [LINK [MODE]]`, `mdns [LINK [MODE]]`, `dnssec [LINK [MODE]]`, `dnsovertls [LINK [MODE]]`, `nta [LINK [DOMAIN...]]`

Get/set per-interface DNS configuration. these commands may be used to configure various DNS settings for network interfaces. they may also be used to inform systemd-resolved or systemd-networkd about per-interface DNS configuration determined through external means. iykyk 🔧

here's the whole squad and what each one expects:

dns — expects IPv4 or IPv6 address specifications of DNS servers to use. each address can optionally take a port number separated with ":", a network interface name or index separated with "%", and a Server Name Indication (SNI) separated with "#". when an IPv6 address is specified with a port number, then the address must be in the square brackets. that is, the acceptable full formats are "111.222.333.444:9953%ifname#example.com" for IPv4 and "[1111:2222::3333]:9953%ifname#example.com" for IPv6. 📝
domain — expects valid DNS domains, possibly prefixed with "~", and configures a per-interface search or route-only domain.
default-route — expects a boolean parameter, and configures whether the link may be used as default route for DNS lookups, i.e. if it is suitable for lookups on domains no other link explicitly is configured for.
llmnr, mdns, dnssec and dnsovertls — may be used to configure the per-interface LLMNR, MulticastDNS, DNSSEC and DNSOverTLS settings.
nta — may be used to configure additional per-interface DNSSEC NTA domains.

also! commands dns, domain and nta can take a single empty string argument to clear their respective value lists. handy 🧼

for details about these settings, their possible values and their effect, see the corresponding settings in systemd.network(5).

Added in version 239.

↩️ `revert LINK`

Revert the per-interface DNS configuration. if the DNS configuration is reverted, all per-interface DNS settings are reset to their defaults, undoing all effects of dns, domain, default-route, llmnr, mdns, dnssec, dnsovertls, nta. like a factory reset but for one link 💫

Note that when a network interface disappears all configuration is lost automatically, an explicit reverting is not necessary in that case.

Added in version 239.

👀 `monitor`

Show a continuous stream of local client resolution queries and their responses. whenever a local query is completed, the query's DNS resource lookup key and resource records are shown. 🦋

Note that this displays queries issued locally only, and does not immediately relate to DNS requests submitted to configured DNS servers or the LLMNR or MulticastDNS zones, as lookups may be answered from the local cache, or might result in multiple DNS transactions (for example to validate DNSSEC information). if CNAME/CNAME redirection chains are followed, a separate query will be displayed for each element of the chain. use --json= to enable JSON output.

Added in version 252.

🗄️ `show-cache`

Show current cache content, per scope. use --json= to enable JSON output. ✨

Added in version 254.

🖥️ `show-server-state`

Show detailed server state information, per DNS Server. use --json= to enable JSON output.

Added in version 255.

📢 `log-level [LEVEL]`

If no argument is given, print the current log level of the manager. if an optional argument LEVEL is provided, then the command changes the current log level of the manager to LEVEL (accepts the same values as --log-level= described in systemd(1)). turn the volume up or down, your call 🔊

Added in version 244.

✨ OPTIONS ✨

okay bestie this is the big one, the option buffet, and every single flag is here so grab a snack 🍓

-4, -6 — so by default, when we're resolving a hostname, we grab both IPv4 and IPv6 addresses, iconic. But if you pass -4 you're like "only IPv4 pls" and if you pass -6 it's "only IPv6 bestie". That's it, that's the whole vibe.

Added in version 239.

-i INTERFACE, --interface=INTERFACE — picks the network interface the query goes out on. You can give it a numeric interface index or a network interface string (like "en0", you know the drill). heads up tho: this option does literally nothing if system-wide DNS configuration is being used instead of per-link configuration — we're talking stuff configured in /etc/resolv.conf or /etc/systemd/resolved.conf. So if you set it and nothing happens, that's why, no cap.

Added in version 239.

-p PROTOCOL, --protocol=PROTOCOL — sets the network protocol for the query. Pick from "dns" (classic unicast DNS, the OG), "llmnr" (Link-Local Multicast Name Resolution[5]), "llmnr-ipv4", "llmnr-ipv6" (that's LLMNR over the IP protocol you named), "mdns" (Multicast DNS[6]), "mdns-ipv4", "mdns-ipv6" (MDNS over the indicated underlying IP protocol). Default behaviour is that the lookup uses all the protocols that suit the lookup, but if you use this option it limits the protocol set. Use it multiple times to enable multiple protocols at once — multitasking queen 👑. Fun fact: "llmnr" is identical to specifying "llmnr-ipv4" once plus "llmnr-ipv6" once. And important: this does not force the service to actually resolve with that protocol, because that might need a suitable network interface and configuration. The special value "help" lists all the known values for you.

Added in version 239.

-t TYPE, --type=TYPE, -c CLASS, --class=CLASS — when you pair these with the query command, they specify the DNS resource record type (like A, AAAA, MX, ...) and class (like IN, ANY, ...) you want to look up. Use them and you get a DNS resource record set matching that class and type. If you only give a type, the class just defaults to IN. And yeah, the special value "help" lists known values here too, very helpful of it.

Without these options, resolvectl query does the high-level domain-name-to-address and address-to-domain-name thing. With them, it's doing low-level DNS resource record resolution. Also: the search domain logic gets automatically turned off when you use these options, meaning any domain names you specify must be fully qualified. And IDNA internal domain name translation is off too, so international domain names need to be written in "xn--..." notation — unless you're looking up in MulticastDNS/LLMNR, in which case use UTF-8 characters instead. Slay, but specific.

Added in version 239.

--service-address=BOOL — takes a boolean. If true (which is the default), when doing a service lookup with --service, the hostnames inside the SRV resource records get resolved as well. Two-for-one, love that for us.

Added in version 239.

--service-txt=BOOL — takes a boolean. If true (the default again), when doing a DNS-SD service lookup with --service, the TXT service metadata record is resolved too. The metadata stays with the metadata, periodt.

Added in version 239.

--cname=BOOL — takes a boolean. If true (default, you know the pattern by now), DNS CNAME or DNAME redirections are followed. If false and a CNAME or DNAME record shows up mid-resolve, you get an error instead. No detours allowed 🚫

Added in version 239.

--validate=BOOL — takes a boolean, used alongside query. If true (the default), DNSSEC validation is applied like normal — but only if it's enabled for the network and for systemd-resolved.service as a whole. If false, DNSSEC validation is disabled for that specific query, no matter whether it's enabled for the network or in the service. And listen, this does not force DNSSEC validation on systems or networks where DNSSEC is turned off — this option is only good for turning validation off where it's otherwise on, never for turning it on where it's otherwise off. Read that twice, bestie, it's giving one-way street.

Added in version 248.

--synthesize=BOOL — takes a boolean, used with query. If true (the default), certain select domains get resolved right on the local system — including "localhost", "_gateway", "_outbound", "_localdnsstub" and "_localdnsproxy", plus entries from /etc/hosts. If false, those domains are not resolved locally: the "localhost", "_gateway", "_outbound"-type ones just fail, and the /etc/hosts entries go out to the network via regular DNS/mDNS/LLMNR lookups instead. Wild, right?

Added in version 248.

--cache=BOOL — takes a boolean, used with query. If true (the default), lookups use the local DNS resource record cache. If false, lookups get routed to the network instead — even if the answer is already sitting right there in the local cache. Fresh fetch only, apparently 💅

Added in version 248.

--zone=BOOL — takes a boolean, used with query. If true (default), lookups get answered from locally registered LLMNR or mDNS resource records, if any are defined. If false, those locally registered LLMNR/mDNS records are simply not considered for the lookup request. Bye ✨

Added in version 248.

--trust-anchor=BOOL — takes a boolean, used with query. If true (default), lookups for DS and DNSKEY are answered from the local DNSSEC trust anchors where possible. If false, the local trust store is not considered for the lookup request. Trust issues, but on purpose.

Added in version 248.

--network=BOOL — takes a boolean, used with query. If true (the default), lookups get answered via DNS, LLMNR or mDNS network requests whenever they can't be synthesized locally or answered from the local cache, zone, or trust anchors (see all the options above, it's a whole ecosystem). If false, the request is not answered from the network at all, so it'll just fail if none of those other sources can answer it. Local-only mode, activated 🔥

Added in version 248.

--search=BOOL — takes a boolean. If true (the default), any single-label hostnames you specify get searched in the domains configured in the search domain list, provided that list isn't empty. Otherwise the search domain logic is disabled entirely. psst: this has zero effect if --type= is used (see above), because in that case the search domain logic is unconditionally turned off. No arguments, it's just off. 🙈

Added in version 239.

--raw[=payload|packet] — dumps the answer records as binary data. If there's no argument, or the argument is "payload", you get the payload of the resource record data — meaning not the whole "RDATA", just the primary contents. If the argument is "packet", the whole resource record is dumped in wire format, prefixed by its length specified as a little-endian 64-bit integer. That format is what lets multiple records be dumped and parsed unambiguously. Clean, no confusion.

Note: "payload" is only supported for a small subset of resource record types — SSHFP, TLSA, OPENPGPKEY (where it dumps just the key material) and A, AAAA (where it dumps the address data). Everything else, sorry, no payload for you.

Also, this option may only be used with --type= or an RFC 4501 "dns:" URI, since both of those do DNS resource record lookups. It may not be combined with regular hostname or address lookups. Rules are rules bestie.

Added in version 239.

--legend=BOOL — takes a boolean. If true (the default), you get column headers and meta information about the query response. Otherwise that output is suppressed and it's just the raw goods.

Added in version 239.

--stale-data=BOOL — takes a boolean, used with query. If true (the default), lookups get answered with stale data — yes, expired resource records — if possible. If false, that stale data is not considered for the lookup request. Expired is still edible, apparently 😭

Added in version 254.

--relax-single-label=BOOL — takes a boolean, used with query. If true, the rules about routing single-label names get relaxed. Defaults to false. By default, lookups of single-label names are assumed to refer to local hosts — to be resolved via local resolution like LLMNR, or via search domain qualification — and they are not routed to upstream servers as-is. Turn this on and those rules are disabled, so the queries get routed upstream anyway. There's also the ResolveUnicastSingleLabel= option in resolved.conf(5) if you want a system-wide version of this behaviour. Big-picture energy.

Added in version 256.

--no-ask-password — don't ask the user for authentication when doing privileged operations. Shhh, we're being sneaky (but politely).
--json=MODE — shows output formatted as JSON. Expects one of "short" (the shortest possible output, no redundant whitespace or line breaks), "pretty" (a pretty version of the same, with indentation and line breaks) or "off" (turns JSON output off — this is the default).
-j — equivalent to --json=pretty if you're running on a terminal, and --json=short otherwise. It just knows, okay? Adaptive king 👑
--no-pager — don't pipe the output into a pager. Scroll freely, bestie.
-h, --help — prints a short help text and exits. The classic.
--version — prints a short version string and exits. Also the classic.

💖 COMPATIBILITY WITH RESOLVCONF(8) 💖

okay bestie, this is the part where resolvectl gets a secret identity. It's a multi-call binary, which is just fancy talk for "it changes what it does depending on the name you call it by". So when you invoke it as resolvconf — and the way you pull that off is usually with a symbolic link named resolvconf pointing at the resolvectl binary — it runs in a limited resolvconf(8) compatibility mode. She accepts mostly the same arguments and shoves all that data into systemd-resolved.service(8), kinda like how the dns and domain commands operate. And heads up: systemd-resolved.service is the only supported backend, which is not how other implementations of this command do it. Different vibes, different rules, periodt. 💅

Also, /etc/resolv.conf will only get updated with servers you add via this command when /etc/resolv.conf is a symlink to /run/systemd/resolve/resolv.conf — and not a static file, okay? There's a whole discussion of /etc/resolv.conf handling over in systemd-resolved.service(8) if you wanna go read it. 📖

And here's the tea: not all operations that other implementations support are supported natively. Specifically, bestie:

-a — registers per-interface DNS configuration data with systemd-resolved. Expects a network interface name as its only command line argument. Reads resolv.conf(5)-compatible DNS configuration data from its standard input. The relevant fields are "nameserver" and "domain"/"search". This one is mostly identical to invoking resolvectl with a combo of the dns and domain commands. And if a relevant input line has invalid syntax, the command fails and leaves your existing per-interface config unchanged. 🫶
- Added in version 239.
-d — unregisters per-interface DNS configuration data with systemd-resolved. This is mostly identical to invoking resolvectl revert.
- Added in version 239.
-f — when you specify this, -a and -d will not complain about missing network interfaces, and they'll silently do absolutely nothing in that case. 🦋
- Added in version 239.
-x — this "exclusive" switch is supported only partially. It maps to an additional configured search domain of "~." — meaning it ensures DNS traffic is preferably routed to the DNS servers on this interface, unless there are other, more specific domains configured on other interfaces.
- Added in version 239.
-p — when specified, the interface will not be used as the default route. Peep systemd-resolved.service(8) for the whole story on the default route.
- Added in version 257.
-m — this switch is not supported and is silently ignored. It's giving ghost. 👻
- Added in version 239.
-u, -I, -i, -l, -R, -r, -v, -V, --enable-updates, --disable-updates, --are-updates-enabled — these switches are not supported, and the command will straight-up fail if you use them. 😭
- Added in version 239.

See resolvconf(8) for the deets on those command line options, k? ✨

🌸 EXAMPLES 🌸

okay this is the fun part, let's actually do stuff 💅

Example 1. Retrieve the addresses of the "www.0pointer.net" domain (A and AAAA resource records)

$ resolvectl query www.0pointer.net
www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74
                   85.214.157.71

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

Example 2. Retrieve the domain of the "85.214.157.71" IP address (PTR resource record)

$ resolvectl query 85.214.157.71
85.214.157.71: gardel.0pointer.net

-- Information acquired via protocol DNS in 1.2997s.
-- Data is authenticated: no

Example 3. Retrieve the MX record of the "yahoo.com" domain

$ resolvectl --legend=no -t MX query yahoo.com
yahoo.com. IN MX    1 mta7.am0.yahoodns.net
yahoo.com. IN MX    1 mta6.am0.yahoodns.net
yahoo.com. IN MX    1 mta5.am0.yahoodns.net

Example 4. Resolve an SRV service

$ resolvectl service _xmpp-server._tcp gmail.com
_xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0]
                             173.194.210.125
                             alt4.xmpp-server.l.google.com:5269 [priority=20, weight=0]
                             173.194.65.125
                             ...

Example 5. Retrieve a PGP key (OPENPGP resource record)

$ resolvectl openpgp zbyszek@fedoraproject.org
d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY
        mQINBFBHPMsBEACeInGYJCb+7TurKfb6wGyTottCDtiSJB310i37/6ZYoeIay/5soJjlMyf
        MFQ9T2XNT/0LM6gTa0MpC1st9LnzYTMsT6tzRly1D1UbVI6xw0g0vE5y2Cjk3xUwAynCsSs
        ...

Example 6. Retrieve a TLS key (TLSA resource record)

$ resolvectl tlsa tcp fedoraproject.org:443
_443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0
        -- Cert. usage: CA constraint
        -- Selector: Full Certificate
        -- Matching type: SHA-256

and just so you know bestie, "tcp" and ":443" are optional and could totally be skipped. 👑

💜 NOTES 💜

RFC 6763 DNS-SD https://tools.ietf.org/html/rfc6763
RFC 2782 SRV https://tools.ietf.org/html/rfc2782
RFC 7929 https://tools.ietf.org/html/rfc7929
RFC 6698 https://tools.ietf.org/html/rfc6698
Link-Local Multicast Name Resolution https://tools.ietf.org/html/rfc4795
Multicast DNS https://www.ietf.org/rfc/rfc6762.txt

and that's a wrap on the whole page, bestie!! 🎀 this one's from systemd 262.1, and it's RESOLVECTL(1) — go forth and resolve some names, you absolute icon. slay 💅✨

📦 where this page comes from

arch rolling: systemd 262.1-1 · LGPL-2.1-or-later AND CC0-1.0 AND GPL-2.0-or-later AND MIT-0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-19: a language model's rewrite of the original, under its terms

RESOLVECTL(1)

💖 RESOLVECTL(1) 💖

✨ NAME ✨

🌸 SYNOPSIS 🌸

🎀 DESCRIPTION 🎀

👑 COMMANDS 👑

🔍 query HOSTNAME|ADDRESS...

🌈 service [[NAME] TYPE] DOMAIN

🔐 openpgp EMAIL@DOMAIN...

🧚 tlsa [FAMILY] DOMAIN[:PORT]...

📊 status [LINK...]

📈 statistics

🔄 reset-statistics

🧹 flush-caches

🔁 reset-server-features

⚙️ dns [LINK [SERVER...]], domain [LINK [DOMAIN...]], default-route [LINK [BOOL...]], llmnr [LINK [MODE]], mdns [LINK [MODE]], dnssec [LINK [MODE]], dnsovertls [LINK [MODE]], nta [LINK [DOMAIN...]]

↩️ revert LINK

👀 monitor

🗄️ show-cache

🖥️ show-server-state

📢 log-level [LEVEL]

✨ OPTIONS ✨

💖 COMPATIBILITY WITH RESOLVCONF(8) 💖

🌸 EXAMPLES 🌸

🦋 SEE ALSO 🦋

💜 NOTES 💜

🔍 `query HOSTNAME|ADDRESS...`

🌈 `service [[NAME] TYPE] DOMAIN`

🔐 `openpgp EMAIL@DOMAIN...`

🧚 `tlsa [FAMILY] DOMAIN[:PORT]...`

📊 `status [LINK...]`

📈 `statistics`

🔄 `reset-statistics`

🧹 `flush-caches`

🔁 `reset-server-features`

⚙️ `dns [LINK [SERVER...]]`, `domain [LINK [DOMAIN...]]`, `default-route [LINK [BOOL...]]`, `llmnr [LINK [MODE]]`, `mdns [LINK [MODE]]`, `dnssec [LINK [MODE]]`, `dnsovertls [LINK [MODE]]`, `nta [LINK [DOMAIN...]]`

↩️ `revert LINK`

👀 `monitor`

🗄️ `show-cache`

🖥️ `show-server-state`

📢 `log-level [LEVEL]`