{{tag>[cli linux systemd systemd-resolved resolvectl dns]}}

====== resolvectl ======
''resolvectl''은 ''systemd-resolved'' resolver의 상태를 조회하고 DNS 질의, cache 관리, link별 DNS server와 routing domain 설정을 수행하는 command-line client다.

===== Installation =====
''resolvectl''은 독립 package가 아니라 ''systemd-resolved''와 함께 제공된다.

==== Debian / Ubuntu ====
<code bash>
sudo apt update
sudo apt install systemd-resolved
sudo systemctl enable --now systemd-resolved
resolvectl --version
</code>

<note warning>
Debian 계열에서 ''systemd-resolved'' package를 설치하면 ''/etc/resolv.conf''가 systemd-resolved 관리 대상으로 전환될 수 있다. 설치 전에 현재 symlink와 network manager 구성을 확인한다.
</note>

==== Fedora / RHEL ====
<code bash>
sudo dnf install systemd-resolved
sudo systemctl enable --now systemd-resolved
resolvectl --version
</code>

RHEL 8에서 ''systemd-resolved''는 Technology Preview로 문서화되어 있으므로 production support 정책을 확인한다. ''systemd''는 Linux 전용이므로 macOS Homebrew와 Windows ''winget''용 공식 설치 방법은 없다.

===== Usage =====
<code bash>
resolvectl [OPTIONS...] COMMAND [NAME...]
</code>

  * ''<color #c3c3c3>**resolvectl**</color> <color #22b14c>[OPTIONS...]</color> <color #ff7f27>query</color> <color #7092be>HOSTNAME|ADDRESS...</color>''
  * ''<color #c3c3c3>**resolvectl**</color> <color #22b14c>[OPTIONS...]</color> <color #ff7f27>dns</color> <color #7092be>LINK [SERVER...]</color>''
  * ''<color #c3c3c3>**resolvectl**</color> <color #22b14c>[OPTIONS...]</color> <color #ff7f27>domain</color> <color #7092be>LINK [DOMAIN...]</color>''

인자 없이 실행하거나 ''status''를 사용하면 global 및 link별 resolver 상태를 표시한다.

===== Query =====
<code bash>
resolvectl query example.com
resolvectl query 192.0.2.10
resolvectl --type=MX query example.com
resolvectl --type=TXT query example.com
resolvectl service _https._tcp example.com
</code>

  * ''query'': hostname, IPv4/IPv6 address 또는 DNS resource record를 조회한다.
  * ''service'': DNS-SD 또는 SRV service를 조회한다.
  * ''openpgp'': email address에 대응하는 OpenPGP key record를 조회한다.
  * ''tlsa'': TLSA record를 조회한다.
  * ''-4'', ''-6'': IPv4 또는 IPv6 결과로 제한한다.
  * ''-i'', ''--interface=INTERFACE'': 질의할 link를 지정한다.
  * ''-p'', ''--protocol=PROTO|help'': DNS, LLMNR, mDNS 등 protocol을 제한한다.
  * ''-t'', ''--type=TYPE|help'': DNS record type을 지정한다.
  * ''-c'', ''--class=CLASS|help'': DNS class를 지정한다.

===== Status and Cache =====
<code bash>
resolvectl status
resolvectl status enp1s0
resolvectl statistics
resolvectl monitor
sudo resolvectl flush-caches
sudo resolvectl reset-statistics
</code>

  * ''status [LINK...]'': 사용 중인 DNS server, protocol, DNS domain과 default-route 상태를 표시한다.
  * ''statistics'': transaction과 cache 통계를 표시한다.
  * ''reset-statistics'': resolver 통계를 초기화한다.
  * ''flush-caches'': local DNS cache를 비운다.
  * ''reset-server-features'': 학습한 DNS server 기능 수준을 초기화한다.
  * ''monitor'': DNS 질의를 실시간으로 감시한다.
  * ''show-cache'', ''show-server-state'': 지원하는 systemd version에서 cache와 server 내부 상태를 표시한다.
  * ''log-level [LEVEL]'': 지원하는 systemd version에서 systemd-resolved의 runtime log level을 조회하거나 변경한다.

===== Per-Link DNS =====
<code bash>
# 임시 DNS server와 search domain 설정
sudo resolvectl dns wlo1 192.0.2.53 192.0.2.54
sudo resolvectl domain wlo1 example.com

# example.com 질의만 이 link로 보내는 route-only domain
sudo resolvectl domain wlo1 '~example.com'

# link별 임시 설정 제거
sudo resolvectl revert wlo1
</code>

''dns'', ''domain'', ''default-route'', ''llmnr'', ''mdns'', ''dnsovertls'', ''dnssec'', ''nta''는 link별 설정을 조회하거나 runtime에 변경한다. 이 설정은 일반적으로 reboot, link 재생성 또는 network manager 재적용 후 유지되지 않는다. 지속 설정은 NetworkManager connection profile, ''systemd-networkd''의 ''.network'' file 또는 ''/etc/systemd/resolved.conf.d/*.conf''에서 관리한다.

++++ 기존 command 기록 |
<code bash>
resolvectl dns wlo1 8.8.8.8 8.8.4.4 # DNS server 설정
resolvectl domain wlo1 zerotyme.net   # DNS domain 설정
</code>
++++

<note warning>
''domain LINK DOMAIN''은 search domain이며, ''~DOMAIN''은 search suffix를 추가하지 않는 route-only domain이다. split DNS에서는 의미가 다르므로 구분한다.
</note>

===== Output Options =====
  * ''--no-pager'': pager를 사용하지 않는다.
  * ''--legend=BOOL'': header와 부가 정보를 표시하거나 숨긴다.
  * ''--json=MODE'', ''-j'': 지원하는 systemd version에서 JSON으로 출력한다.
  * ''--raw[=payload|packet]'': 응답을 binary payload 또는 packet으로 출력한다.
  * ''--validate=BOOL'', ''--synthesize=BOOL'', ''--cache=BOOL'', ''--stale-data=BOOL'', ''--zone=BOOL'', ''--trust-anchor=BOOL'', ''--network=BOOL'', ''--search=BOOL'': 지원하는 version에서 lookup source와 검증 동작을 제어한다.

option과 command는 systemd version에 따라 다를 수 있으므로 대상 host의 ''resolvectl --help''를 기준으로 확인한다.

===== Help =====
++++ resolvectl --help |
<code text>
resolvectl [OPTIONS...] {COMMAND} ...

Send control commands to the network name resolution manager, or
resolve domain names, IPv4 and IPv6 addresses, DNS records, and services.

  -h --help                    Show this help
     --version                 Show package version
     --no-pager                Do not pipe output into a pager
  -4                           Resolve IPv4 addresses
  -6                           Resolve IPv6 addresses
  -i --interface=INTERFACE     Look on interface
  -p --protocol=PROTO|help     Look via protocol
  -t --type=TYPE|help          Query RR with DNS type
  -c --class=CLASS|help        Query RR with DNS class
     --service-address=BOOL    Resolve address for services (default: yes)
     --service-txt=BOOL        Resolve TXT records for services (default: yes)
     --cname=BOOL              Follow CNAME redirects (default: yes)
     --search=BOOL             Use search domains for single-label names
     --raw[=payload|packet]    Dump the answer as binary data
     --legend=BOOL             Print headers and additional info

Commands:
  query HOSTNAME|ADDRESS...    Resolve domain names, IPv4 and IPv6 addresses
  service [[NAME] TYPE] DOMAIN Resolve service (SRV)
  openpgp EMAIL@DOMAIN...      Query OpenPGP public key
  tlsa DOMAIN[:PORT]...        Query TLS public key
  status [LINK...]             Show link and server status
  statistics                   Show resolver statistics
  reset-statistics             Reset resolver statistics
  flush-caches                 Flush all local DNS caches
  reset-server-features        Forget learnt DNS server feature levels
  dns [LINK [SERVER...]]       Get/set per-interface DNS server address
  domain [LINK [DOMAIN...]]    Get/set per-interface search domain
  llmnr [LINK [MODE]]          Get/set per-interface LLMNR mode
  mdns [LINK [MODE]]           Get/set per-interface MulticastDNS mode
  dnsovertls [LINK [MODE]]     Get/set per-interface DNS-over-TLS mode
  dnssec [LINK [MODE]]         Get/set per-interface DNSSEC mode
  nta [LINK [DOMAIN...]]       Get/set per-interface DNSSEC NTA
  revert LINK                  Revert per-interface configuration
</code>
++++

===== Troubleshooting =====
  * ''Failed to get global data: Unit dbus-org.freedesktop.resolve1.service not found'': ''systemd-resolved'' package와 service 상태를 확인한다.
  * ''resolvectl status''에는 DNS server가 있지만 질의가 실패함: ''resolvectl query'', ''journalctl -u systemd-resolved'', firewall의 UDP/TCP 53 경로를 확인한다.
  * ''/etc/resolv.conf''가 ''127.0.0.53''을 가리킴: 정상적인 local stub mode일 수 있다. 실제 upstream server는 ''resolvectl status''로 확인한다.
  * runtime 설정이 사라짐: ''resolvectl dns/domain'' 대신 사용 중인 network manager의 persistent profile에 저장한다.
  * ''domain'' 설정 후 예상하지 않은 suffix 질의가 발생함: route-only domain이 필요하면 ''~example.com'' 형식을 사용한다.

===== Compatibility =====
''resolvectl''은 systemd 239부터 이전 ''systemd-resolve'' client를 대체했다. 일부 command와 option은 이후 systemd release에서 추가되었으므로 오래된 distribution에서는 표시되지 않을 수 있다.

===== See Also =====
  * [[systemd-resolved:ko|systemd-resolved]]
  * [[linux:path:etc:resolv.conf|/etc/resolv.conf]]
  * [[networkmanager:nmcli:ko|nmcli]]
  * [[https://www.freedesktop.org/software/systemd/man/latest/resolvectl.html|resolvectl upstream manual]]
  * [[https://www.freedesktop.org/software/systemd/man/latest/systemd-resolved.service.html|systemd-resolved upstream manual]]

===== History =====
  * codex:: 2026-07-19 기존 DNS와 domain 설정 기록을 보존하고 설치, 질의, 상태, cache, per-link 설정과 troubleshooting을 추가했다.

{{indexmenu>.#1|js}}