resolvectl: Usage, Options & Common CI Errors
resolvectl talks to systemd-resolved to resolve names and show DNS config.
On systemd hosts, /etc/resolv.conf points at the 127.0.0.53 stub resolver, so the real DNS servers live in systemd-resolved. resolvectl is how you see what is actually configured and flush a stale cache.
What it does
resolvectl is the client for systemd-resolved. It resolves names (resolvectl query), reports the per-interface DNS servers and search domains (resolvectl status), and clears the resolver cache (resolvectl flush-caches) on hosts where /etc/resolv.conf is just the 127.0.0.53 stub.
Common usage
resolvectl query example.com
resolvectl status # configured DNS servers per link
resolvectl flush-caches # clear the resolver cache
resolvectl statistics # cache hits/misses
resolvectl dns # show DNS servers in useOptions
| Subcommand | What it does |
|---|---|
| query <name> | Resolve a name via systemd-resolved |
| status | Show DNS servers, search domains per link |
| flush-caches | Drop the resolver cache |
| statistics | Cache and transaction stats |
| dns [link] [servers] | Show or set DNS servers |
Common errors in CI
Reading /etc/resolv.conf shows only "nameserver 127.0.0.53" - that is the stub, not the real upstream; use resolvectl status to see the actual servers. "Failed to ... resolved.Manager: Connection refused" or "systemd-resolved.service not running" means resolved is not active (common in containers) - there is nothing to query; fall back to getent hosts or dig. resolvectl is mostly host/VM-relevant; minimal containers do not run systemd-resolved at all, so do not rely on it inside slim images.